Skip to content

0008. Modular monolith with hexagonal ports, two deployment targets, and three composition roots

  • Status: Accepted
  • Date: 2026-11-08

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
  • 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′:
    • one SQLite-backed Durable Object (DO) per project holds the project’s data and schedules its runs with alarms (ADR 0010, ADR 0011);
    • Queues carry delivery work;
    • D1 is the control plane (workspaces, users, keys, routing, roll-ups);
    • R2 holds blobs and archives.
  • Self-host: either the same Cloudflare deployment, or containers: the apps/node Docker image on Postgres, with a per-project advisory lock, a polling scheduler using SKIP 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) and tracker (click redirects).
    • apps/node: one Docker image with entrypoints api, tracker, delivery, scheduler, and all.
    • apps/dashboard: the React + Vite SPA (ADR 0028).
    • The managed service’s cloud composition root lives in cloud/ and wraps the apps/workers factories with cloud extensions. Public code never imports cloud/.
  • 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).
  • 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 is apps/workers.