Decisions
Architecture decision records (ADRs). Each file records one decision: its context, the decision, and its consequences. Use the write-adr skill to add one.
| ADR | Title | Status |
|---|---|---|
| 0001 | Positioning against Customer.io and billing basis | Superseded by 0014 |
| 0002 | Private source repository, public OSS sync, and cloud switch | Accepted |
| 0003 | Managed service first, free self-hosting later | Accepted |
| 0004 | MVP scope | Superseded by 0015 |
| 0005 | REST, MCP, OpenAPI, and docs parity | Accepted |
| 0006 | Engineering conventions | Accepted |
| 0007 | Core invariants | Accepted |
| 0008 | Modular monolith with hexagonal ports, two deployment targets, and three composition roots | Accepted |
| 0009 | Platform-neutral ports with contract tests on every target | Accepted |
| 0010 | Project data store: SQLite DO or Postgres, Kysely repositories, capacity, retention, and archival | Accepted |
| 0011 | Run scheduling and delivery: the project store owns all retries | Accepted |
| 0012 | Unknown send outcomes and metering at provider acceptance | Accepted |
| 0013 | Workspace send budget and plan-limit behaviour | Accepted |
| 0014 | Single-plan pricing by emails per month, and dated positioning against Customer.io | Accepted |
| 0015 | MVP scope with time-based triggers and SES | Accepted |
| 0016 | Time-based triggers: types, fire index, fire keys, timezones, and activation confirmation | Accepted |
| 0017 | Workflow run identity, re-entry policy, and stop | Accepted |
| 0018 | Module boundaries and their automated enforcement | Accepted |
| 0019 | One action registry with api and endpoint kinds |
Accepted |
| 0020 | Click tracking with self-contained signed tokens and a separate tracker | Accepted |
| 0021 | Encryption of stored secrets and hashing of credentials | Accepted |
| 0022 | Toolchain, repository layout, and Docker scope | Accepted |
| 0023 | Customer deletion with tombstones so replays cannot recreate data | Accepted |
| 0024 | Amazon SES with one tenant per workspace, and our own sender protection | Accepted |
| 0025 | Authentication with Better Auth: email codes, Google, and MCP OAuth | Superseded by 0040 |
| 0026 | Workspace roles, project API keys, and MCP grant scopes | Accepted |
| 0027 | AGPL-3.0, personally held copyright, and no external pull requests yet | Accepted |
| 0028 | Dashboard as a static SPA on the API’s origin | Accepted |
| 0029 | System mail through Cloudflare Email Service, separate from workspace mail | Accepted |
| 0030 | Walking skeleton: tool versions and implementation decisions | Proposed |
| 0031 | MCP surface: stateless JSON-RPC over the action registry, with output schemas | Proposed |
| 0032 | No personal data or secrets in server logs, enforced by one redacting logger | Accepted |
| 0033 | Sending workflows go live only after a human approves them out of band | Accepted |
| 0034 | Amazon SES adapter: SESv2 over fetch, outcome classification, sending domains, and events through EventBridge | Accepted |
| 0035 | Sending domains are written through operator endpoints and replicated to project stores in version order | Accepted |
| 0036 | One-click unsubscribe links carry a per-attempt random token stored as a hash | Accepted |
| 0037 | Each workspace’s provider tenant has a Region, chosen from a configured allowlist | Accepted |
| 0038 | Operator alerts are outbox entries keyed by incident, raised through an extension point | Accepted |
| 0039 | Sending domains and provider tenants are provisioned at runtime by one paced job runner per Region | Proposed |
| 0040 | Sign-in with Better Auth on Workers and D1: email codes and Google, cookie sessions, and rate limits in D1 | Accepted |
| 0041 | Users, workspace memberships, and the user principal of API actions | Accepted |
| 0042 | A static public site on the apex domain serves the landing page, pricing, legal pages, and the docs | Accepted; its “One environment” rule is to be superseded by 0052 (Proposed) |
| 0043 | The product keeps the name “Customer.lite” | Accepted |
| 0044 | Send approval is optional per workspace and off by default, with pause and rollback | Proposed (optional approval, off by default: Accepted) |
| 0045 | Saved audiences: one condition language, dynamic audiences pinned by an expanded copy, and counts by bounded scans | Proposed (event-name cap, deferred audience triggers: Accepted) |
| 0046 | Open tracking with a pixel, and machine-open classification by one core function | Proposed (tracking defaults: Accepted) |
| 0047 | Analytics from message facts: idempotent first-time facts, reports by grouping in the project store, and conversions in a run’s conversion window | Proposed (recipient-level reads, report days, conversion window, 90-day fact retention, re-entry during the window: Accepted) |
| 0048 | A/B experiments on send steps: two variants and an optional holdout, sticky assignment, a matured fixed horizon, and a winner chosen by a person or their AI | Proposed (A/B and holdout in the first release, human or AI winner, fixed-horizon statistics: Accepted) |
| 0049 | Broadcasts are one-off sends stored as generated workflows with a once trigger |
Proposed |
| 0050 | Every action that can start sends is confirmed on the server: a preview with an exact count and a token, then a committing call | Proposed (confirmation in every workspace: Accepted) |
| 0051 | MCP OAuth in the first release: Better Auth’s authorization server, and grants that act as their user on one project | Proposed (OAuth for claude.ai, ChatGPT, and Claude Code in the first release: Accepted) |
| 0052 | Staging gets a noindex copy of the public site on a host of its own, with no redirect | Proposed (a public site checkable on staging: Accepted) |
Status values: Proposed, Accepted, Superseded by NNNN. Do not edit the decision of an Accepted ADR; write a new ADR that supersedes it.