A Carrier reference architecture gives teams a repeatable starting point. It should be opinionated enough to create consistency, but not so rigid that every service is forced into the same shape.
Recommended Repository Layout
A common Carrier service layout uses sorted layers (00_models/, 10_types/, 20_actions/, 30_routes/, 40_async/). For larger domains, prefer domain folders. src/main.carrier should be the build root. Carrier follows the transitive import graph from that file, so unimported sibling files should not be assumed to participate in the build.
Domain Module Strategy
Reusable modules should live under modules/<org>/<name>/src/. Imports remain namespaced (forms.Submission, forms.submit(...)). Shared modules should be used for stable reusable concepts, not as dumping grounds for unclear ownership. Good candidates include shared questionnaires, common value types, integration contracts, and reusable pure helpers.
Secure Service Template
A secure Carrier service template should include a declared service, JWT authentication when routes are protected, models reviewed for sensitive and tenant-scoped data, named request and response types, actions for business workflows, thin routes, policies for role and tenant visibility, OpenAPI generation in CI, manifest inspection in CI, and migration review for schema changes. Security should not be left to route-handler convention.
API Governance Pipeline
A mature Carrier API governance pipeline runs the format, check, build, openapi, and (when relevant) migrate generate commands. The pipeline should compare generated OpenAPI and manifest output against the previous baseline. Carrier source is the architectural source of truth; generated OpenAPI, migrations, and manifests are governance evidence.