Contributing
Repo layout and layers
The folders of the CirCI repository, the five layers and the rules that keep them apart.
CirCI is a pnpm and Turborepo monorepo. Code is split into five layers, and the dependencies between them are checked by a test (packages/services/test/layers.test.ts) and by lint overrides in .oxlintrc.json, so a wrong import fails before review.
The layers
Section titled “The layers”Read the diagram from the top: a request enters at the transport layer and each layer calls the one below it. core and api depend on nothing.
| Layer | Lives in | May import |
|---|---|---|
| Transport | apps/server (http/, cli/, composition/), apps/worker, apps/web |
Services, @circi/db/queries (read models) and types. Never repositories, the queue, the schema, drizzle-orm or pg. The composition root is the one app folder that wires the database |
| Services | packages/services/src/<area>/ |
Core, db, adapters. No app, Fastify, auth, api or config |
| Core | packages/core |
Nothing from @circi, no I/O. @circi/core is browser-safe; @circi/core/node holds the Node-only secrets, tokens and signing |
| Db | packages/db |
Core. Never services, integrations, storage, auth or api |
| Adapters | packages/integrations, storage, diff, sites |
At most core (integrations also api), never db, services or Fastify |
packages/config and packages/api (wire types, types only) sit beside the stack: config imports at most core, and nothing outside config reads process.env. packages/auth imports no service or app, and the web app imports no server package.
Folders
Section titled “Folders”apps/
server/ ## the circi command: HTTP routes (CI API, dashboard, sign-in), admin CLI, composition
worker/ ## background jobs: claim loop and thin job adapters (inlined in the server bundle)
web/ ## the dashboard (React, TanStack Router and Query, Base UI), organized by feature
packages/
api/ ## the wire types of the dashboard API (types only)
auth/ ## better-auth composition, admin operations
cli/ ## circi upload for CI
config/ ## environment parsing and validation
core/ ## rules with no I/O: baselines, pairing, outcomes, limits, slugs, review rules
db/ ## Drizzle schema, migrations, repositories, queries (dashboard read models), queue
diff/ ## PNG validation, pixel diffs (JS, worker threads, native Rust), thumbnails
integrations/ ## the integration SDK and one folder per kind (GitHub, GitLab, ...)
services/ ## use cases: transactions, repositories, queued jobs and notices
sites/ ## hosted-site handling
storage/ ## local-disk and S3 drivers, checksum-verified writes
testing/ ## db-free test support
ui/ ## the design system: Base UI parts, CSS modules, --circi-* tokens
vitest/ ## @circi/vitest
deploy/ ## the reference install
dev/ ## the local QA environment behind pnpm dev
e2e/ ## end-to-end tests against the Docker stack
perf/ ## the k6 performance suite
docs/ ## architecture review, design gaps, integration SDK guide, perf results, plans, reference notesThe rules
Section titled “The rules”@circi/dbsubpaths say the layer. Import@circi/db/queries,/repositories,/queueor/schema; the root is the connection, errors and shared types.- Repositories store and look up, nothing else. They never queue jobs; a repository that changes something returns what happened and the caller decides what follows.
- Services own every change that triggers something. The service opens the transaction and queues the jobs and notices, so a webhook delivery or check run exists exactly when the change is committed (a transactional outbox). The build pipeline is the one exception: it's idempotent step by step, so no connection is held across image work.
- Read models (
db/queries) are shaped for the dashboard, and their return types must fit@circi/api:apps/server/src/contract-check.tsfails to typecheck if they drift. Routes may call them directly. - Routes decide no roles. Use the policies in
services/src/access. A route file stays under 250 lines. - Better-auth's tables (
schema/auth.ts) are generated (pnpm db:auth-schema, thenpnpm db:generate), never edited by hand. - Fastify scopes receive exactly their dependencies; register a scope with a prefix through a wrapper plugin, so the plugin's options never carry
prefix.
A file that breaks a rule on purpose is a named exception in the test, with its reason.
Where does new code go?
Section titled “Where does new code go?”| You are adding | Put it in |
|---|---|
| An endpoint | The route in apps/server/src/http/routes/<area>/, the use case in packages/services/src/<area>/, the read model in packages/db/src/queries/, the store in packages/db/src/repositories/, the wire type in packages/api |
| A background job | A body in services/src/jobs/ or the area folder and a thin adapter in apps/worker/src/handlers/. Never a new job name or payload key without a rolling-deploy plan, because queued rows outlive a deploy |
| A pure rule | packages/core |
| An integration | One folder under packages/integrations/src/kinds/, listed once in the registry (see Integrations overview) |
Services tests mirror the folders under packages/services/test/.
Conventions
Section titled “Conventions”- Types that belong to something live in type-only namespaces (
createBuild.Input,Row.Props,Build.Detail). A namespace contains only types, never a value. - Imports use the
#folder/*aliases from each package'spackage.json, not../../..climbs. - CSS modules:
styles.root. Colors and sizes come from--circi-*tokens, never copied hex values. - Copy: contractions with the straight apostrophe, "ID", "Delete" for something gone for good and "Remove" for taking it out of a list, "screenshot" never "snapshot".
The integration SDK
Section titled “The integration SDK”Every integration is one definition in packages/integrations/src/kinds/<id>/, listed once in one registry. The definition says:
- the credentials form (the dashboard draws its fields from it) and how to verify them with the provider,
- what the provider can do (the capabilities: send chat messages, create issues, list and link design frames, act as a git host),
- how a project maps to a target, and which events it wants,
- when an error means a person has to act.
The Add dialog, the HTTP routes, the worker job and the mapping page all read that definition, so a new integration needs no route, table or page of its own.