Skip to content

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.

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.

The five layers of the CirCI code baseFrom top to bottom: transport (apps/server, apps/worker, apps/web), services, core, db and adapters. Each layer calls the one below it.Transportapps/server · apps/worker · apps/webParse the request, check who is asking,call a service or a read model, shape the replyServicespackages/servicesUse cases: open the transaction, callrepositories, queue the jobs and noticesCorepackages/coreRules with no I/O: baselines, outcomes,limits, review rulesDbpackages/dbqueries (read models) · repositories (stores)queue · schemaAdapterspackages/integrations · storage · diff · sitesTalk to GitHub, Slack, S3 and images
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.

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 notes
  • @circi/db subpaths say the layer. Import @circi/db/queries, /repositories, /queue or /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.ts fails 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, then pnpm 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.

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/.

  • 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's package.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".

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.