0008. Modular monolith with hexagonal ports, two deployment targets, and three composition roots
- Status: Accepted
- Date: 2026-11-08
Context
Section titled “Context”The managed service runs on Cloudflare only and must have near-zero fixed cost, with cost scaling with emails, events, and storage. Self-hosters must be able to run the same product either on Cloudflare or in containers (for example Docker or ECS with Postgres). The workflow step types are fixed data (ADR 0015), so a run is a small state machine that core interprets; a general durable-execution engine (Cloudflare Workflows, Inngest) would add a second copy of run state, and Cloudflare does not document how in-flight Workflow instances behave across deploys.
Options compared (Cloudflare pricing and limits checked 2026-11-07):
| Option | Why not chosen |
|---|---|
| P: Postgres everywhere (Neon via Hyperdrive on Cloudflare) | Every managed request pays a compute floor (about $19/month once any tenant keeps compute awake) and a cross-region hop, for a benefit only self-hosters get |
| B: sharded D1 + Workflows + Queues | D1 has a single writer and 10 GB per database and no runtime binding per project; Workflows has no container equivalent |
| Microservices, event sourcing | Operational cost and projections that one small team does not need |
Decision
Section titled “Decision”- Style: a modular monolith with a hexagonal core. Core is pure TypeScript with platform-neutral ports (ADR 0009); adapters implement them per target.
- Managed service (Cloudflare only), option A′:
- Self-host: either the same Cloudflare deployment, or containers: the
apps/nodeDocker image on Postgres, with a per-project advisory lock, a polling scheduler usingSKIP LOCKED, a Postgres jobs table as the default delivery queue (SQS optional), S3 for blobs, and Secrets Manager or environment variables for keys. The container path is required before the open-source release, not for the managed MVP. - Composition roots:
apps/workers: the Cloudflare deployment. Two Workers:api(REST, MCP, inbound and provider webhooks, Queue consumers, and the project DO class) andtracker(click redirects).apps/node: one Docker image with entrypointsapi,tracker,delivery,scheduler, andall.apps/dashboard: the React + Vite SPA (ADR 0028).- The managed service’s cloud composition root lives in
cloud/and wraps theapps/workersfactories with cloud extensions. Public code never importscloud/.
- Same-origin routing on both targets: the API and the dashboard share the app domain, with the path table in ADR 0028; the tracker serves click redirects on a separate tracking domain (ADR 0020).
Consequences
Section titled “Consequences”- Portability costs two storage implementations (DO SQLite and Postgres). The contract suite (ADR 0009) and shared repository code (ADR 0010) keep them aligned.
- Isolation on the managed service is physical: a project’s DO contains only that project’s data.
- Cross-project queries (billing, abuse, admin search) cannot scan DOs; they read a roll-up sink (ADR 0010).
- If container self-hosting becomes the main channel, option P should be reconsidered in a new ADR.
- The earlier proposal named the Cloudflare root
apps/cloudflare; the name isapps/workers.