Docs
Repository map
Repository map
Where HTTP routes, schemas, contracts, workers, and tests live in the Cascades monorepo.
Quick map
| Concern | Location |
|---|---|
| HTTP routes (App Router) | app/api/**/route.ts |
| OpenAPI fragments (Zod) | Co-located app/api/**/schema.ts (required — npm run audit:api) |
| Aggregated OpenAPI document | lib/api/openapi.ts → generated openapi/cascades-openapi.json → served at /openapi.json |
| SDK / third-party HTTP boundary | contracts/api.yaml (subset of full OpenAPI; mirrored to cascades-sdk) |
| Shared Zod building blocks | lib/schemas/shared/*, lib/schemas/api/* |
| Workflow graph / node typing | lib/workflows/schema.ts (facade re-export: lib/schemas/workflows/index.ts) |
| Orchestration + execution | lib/orchestration, lib/executors, lib/workflows |
| Queue + workers | lib/queue, workers/*.ts |
| Prisma schema + migrations | prisma/schema.prisma, prisma/migrations/ |
| Thin data helpers | lib/data/* (expand over time) |
| Consistent JSON errors (optional migration) | lib/api/http-errors.ts |
| Vitest | tests/**/*.test.ts (vitest.config.ts) |
| Playwright E2E | tests/e2e/*.spec.ts |
Commands
npm run audit:api— everyroute.tshasschema.tsnpm run generate:openapi— refreshopenapi/cascades-openapi.jsonnpm run validate:contract—contracts/api.yamlstays aligned with generated OpenAPI for SDK paths
See also Architecture and OpenAPI contract.