API & OpenAPI

The backend is spec-first: backend/openapi.yaml is the source of truth for the REST API. The server handlers and the typed frontend client are generated from it — you change the spec first, then regenerate code, never the other way around.

Multi-file spec layout

The spec is split across multiple files so it stays maintainable:

backend/
  openapi.yaml      # root: info, servers, components, tags, and $ref index
  paths/<domain>.yaml     # operations, one file per tag/domain
  schemas/<domain>.yaml   # schemas, one file per domain

The convention is one tag = one paths/ file = one schemas/ file.

Resource groups

The API is organised into these domains (one paths/*.yaml file each):

Group	Group
`activities`	`agents`
`ai-tools`	`api-keys`
`artifacts`	`attachments`
`auth`	`backoffice`
`blueprints`	`contact`
`embedding-providers`	`feeds`
`github`	`health`
`invitations`	`memories`
`notifications`	`projects`
`prompts`	`search`
`subscriptions`	`support`
`teams`	`types`
`user`	`webhooks`

Shared schema definitions live in schemas/common.yaml; other schemas/*.yaml files mirror the path domains.

Bundling

The multi-file source is bundled into a single artifact with Redocly before linting, docs, and code generation:

make backend-bundle-openapi
# → backend/dist/openapi.bundled.yaml

Always consume the bundle (dist/openapi.bundled.yaml), not the source tree.

Validation & linting

make backend-validate-openapi   # structural validation (swagger-cli)
make backend-lint-openapi       # ruleset linting (vacuum, Spectral-format ruleset)

CI runs both, so run them locally before committing.

Code generation

The bundle drives oapi-codegen, which produces the strict-server bindings and shared types. The generated code is committed and must never be hand-edited:

make backend-generate-openapi-server

See Code Generation for the full set of generators (oapi-codegen, Wire, mockery) and the golden rules around them.

The API-change flow

A change to the API ripples through three repos in order:

Update the spec. Edit backend/paths/*.yaml / backend/schemas/*.yaml, then regenerate the server (make backend-generate-openapi-server) and implement the handler/service/repository logic. Validate and lint the spec.
Release a new @vibexp/api-client. The typed client is generated from the spec in the separate api-client-js repo and published to npm.
Bump the frontend dependency. Update the frontend to the new @vibexp/api-client version and use the new endpoints/types.