Skip to content

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.