Skip to main content

ADR-0003: Three processes from one codebase

Status​

Accepted. Observed from the entry files and Compose. The decision to split processes rather than threads was not separately written down.

Context​

HTTP, Bull consumers, and cron ticks have different scaling and failure behavior. Channel sync and outbox dispatch must not depend on an API replica serving traffic.

Decision​

ProcessEntry
APIsrc/main.ts
Workersrc/main.worker.ts, including the outbox dispatcher
Schedulersrc/main.scheduler.ts

Compose runs them from one image with different commands. The scheduler is documented as single-replica in AI_CONTEXT.md.

Alternatives​

Not recorded. This is not a set of independently deployed domain services. Areas are modules in one monolith.

Consequences​

  • Starting only the API leaves outbox rows undispatched and crons idle.
  • A listener must be imported by the process that should run it.
  • PartitionMaintenanceService runs on the worker because that module loads it.
  • Replica counts in production were not confirmed from the deploy workflow.