Product

The product

A catalog API with a web console over it. The catalog is the source of truth the rest of the Fleetworks suite reads from and registers into.

Open the app How it works

The catalog

Six core resources: Service, Agent, Team, AWS account, Azure account and Label. A Service carries around ninety fields: ownership, contacts, links, accounts, compliance metadata and dependencies.

Compositions and VCS tenants are cataloged too. A Composition declares a group of Services and Agents with a dependency order and a wiring map; Yellow Pages validates it and resolves its plan but never deploys it. A VCS tenant is one GitHub org, GitLab group or Azure DevOps org.

Access rules on every row

Every catalog resource has an owner, at most one owner group and a Mode: chmod-style view, edit and delete bits for the owner, the owner group and everyone else.

The default Mode is 484, public-read: the owner may do everything and everyone else may view. Mode 480 adds view for the owner group only; Mode 448 is private to the owner.

A REST API over all of it

The API is built with Hono and describes itself in OpenAPI. Its resource paths keep the legacy Yellowpages contract (/api/service, /api/team, /api/aws_accounts and so on) while adding relational integrity and modern auth.

Writes need a signed-in principal or an API key with write scope, and then pass the Mode check. A CI job re-dumps the OpenAPI document from the route definitions and fails on any drift.

The web console

A Next.js console with list, detail and edit pages for each resource, cross-resource search, an audit view, and settings for API keys, webhooks and connectors. Public rows are browsable without an account.

Machines and other systems

API keys are machine principals with read or write scope. Webhooks deliver signed, minimized notices of catalog changes. Connectors show a Service’s data from Coastguard and DNS on its detail page.

Coastguard registers Agents through an idempotent registration call. Warden reads VCS tenants. Helmsman can act as the directory provider for teams and people.

Mobile and desktop

The repo also contains an Expo mobile app for browsing the catalog, with search, an audit tab, and report and block for user content. Its builds go to TestFlight through a manual release workflow; this site does not offer a store download.

A Tauri desktop shell exists in the repo. No desktop release has been published, so there is nothing to download yet.

At a glance

API: REST, Hono with OpenAPI, document at /openapi.json
Database: PostgreSQL through Drizzle ORM
Sign-in: Zitadel (OIDC), the shared Fleetworks identity provider
Default Mode: 484, public-read
API key format: yp_…, shown once, hashed at rest
Webhook signature: HMAC-SHA256 in X-YP-Signature
Connector timeout: 3 seconds, partial results on failure