Architecture decision register

These are CTO recommendations for this design version. They do not approve new spending, select pilot participants or replace the PRD. Prior ADR files remain unchanged historical sources.

ADR-005: TypeScript Workers and D1 for the bounded pilot

Proposed. Choose one language across UI and domain packages, D1 per environment, R2 raw intake and Queues for bounded jobs.

D1 wins on cost and operational scope for the assumed pilot. Its single-threaded query execution and database-size ceiling are critical drawbacks. Postgres wins if measured write contention, operator complexity or location requirements exceed D1. Go is viable when an essential parser or workload demands it; no such evidence is established. Any future Containers design must specify instance maximum, sleep policy, memory/CPU bounds and a new worst-case bill before approval.

Acceptance gate: deployed Workers spike demonstrates auth, Connect, MIME parsing, D1 conditional batch publication and the CPU envelope. Failure returns this ADR to review; engineers must not add a paid backend quietly.

ADR-004 revision 2: Versioned calculation results

Proposed replacement of the old technical model. Rules use a validated finite DSL, immutable sources and explicit operator support. Complete account result revisions replace one mutable eligible-spend accumulator.

This costs more implementation and stored metadata. It is necessary because minimum qualification, bonus caps, partial purchase coverage, quarterly gates and refund adjustments are different ledgers. A daily correction must reconcile every screen and explain historical changes. Unapproved 80% warnings, ten-push daily limits and blanket switch-card copy are withdrawn. Push remains a separate future product decision.

ADR-001 amendment: Central tagged intake with primary revocation

Addressing direction retained; storage/revocation amended. One central routing pattern with random per-user tags remains. Tags identify the account, not a trusted sender. Use primary D1 to revoke immediately, encrypted reveal values and an R2/D1 outbox for durable intake. The old KV revocation shortcut and assumed 30-day raw retention are not used. Seven days is a pending policy proposal.

A primary lookup increases per-message SQL use. This is preferable to accepting revoked tags from a stale cache. Provider subaddressing and SMTP failure behaviour still need live forwarding tests.

ADR-002 amendment: Safe shared categories, optional AI

Lookup direction retained; model activation gated. Use personal overrides before verified business aliases. Three agreeing users produce a reviewed promotion candidate. No personal-name text is promoted automatically. Merchant categories and inferred codes do not establish bank MCC eligibility.

DeepSeek versus GLM remains unresolved. Do not reuse old model-name, neuron, privacy or price assumptions. An engineer benchmarks roughly 200 labelled redacted descriptors, tests calibration and abstention, and measures current provider usage. Proposed activation bar is at least 90% accuracy on high-confidence answers, with unknown rate disclosed. The Owner approves any nonzero incremental AI budget. No indefinite queue builds while disabled.

ADR-003 amendment: Google-only responsive web app

Google-only decision retained. Use React/TanStack on Workers, internal identity linked to Google's subject, and a server session. A PWA shell may be considered later, but installation prompts, offline financial caching and push are not prerequisites of this design. This removes the prior implication that phone-first automatically approves push or install onboarding.

The session policy changes from implicit sliding expiry to explicit renewal so read RPCs remain side-effect free. Renewal remains a protected POST. Library selection stays with the compatibility spike.

ADR-006: Private snapshots and conservative caching

Proposed. Financial reads use no shared cache. Public immutable rule versions may be cached; selection of the applicable version uses authoritative data. Client memory caches are account-scoped and invalidated together after a revision publishes. No offline persistence of private results by default.

This trades some repeated reads for simpler privacy and revision consistency. Revisit only with measured cost or latency evidence and a stated PRD staleness requirement.