Optima technical design

Technical design v0.1 · Kai, CTO · 2 November 2026

Status: proposed technical baseline for review. This document does not declare the product Ready or authorize a real-data pilot.

The design turns PRD v1.1 into a system that captures forwarded alerts, preserves uncertain evidence and explains reward progress across multiple cards. The reviewed visual reference is mockup v0.17 revision 3. The currently published mockup may lag that reference.

Read the design

1. Architecture explains deployment and module boundaries.
2. Journeys contains sequence diagrams for J1–J4, ingestion and deletion.
3. Data defines records, ownership and consistency.
4. Reward engine specifies periods, rounding, caps and revisions.
5. RPC contract defines reads, writes, errors and compatibility.
6. Security and privacy covers access, forwarding trust and deletion.
7. Caching and operations covers retries, recovery and deployment.
8. Cost and effort states assumptions, ceilings and estimates.
9. Decisions compares options and reconciles the old ADRs.
10. Readiness and sources maps requirements to evidence and open gates.

Decisions I recommend

• Run React, TypeScript, TanStack Router, Query and Start on Workers. Use one modular backend, not a fleet of services.
• Use D1 for the bounded pilot and R2 for temporary raw MIME. Keep storage access behind owned repositories to permit a later Postgres migration.
• Use Protobuf and Connect RPC. Backend owns the schema; Frontend reviews it before either implementation starts.
• Publish complete calculation revisions atomically. Never assemble a dashboard from independently updated totals.
• Keep merchant inference asynchronous and disabled until its quality, privacy and cost gates pass. Capturing known amounts does not depend on it.

Decisions still needed

Exact pilot products and their terms are unresolved. Pia recommends three candidate products, conditional on participant ownership; this is not an approved list. Raw-email retention and deletion wording need Owner and privacy review. The proposed seven-day raw retention window is not a promise.

The cost model assumes an Estimated 100-account pilot, not permission to limit the agreed product scope. Larger cohorts need fresh capacity and cost review. No paid service beyond the existing US$5 Workers plan is authorized here.

What this document replaces

This design revises the technical proposals in ADR-001 through ADR-004. It withdraws their assumed 30-day raw retention, KV-based immediate tag revocation, simplified eligible-spend accumulator and unapproved push-alert thresholds. Existing ADR files remain historical records. The decision register identifies each amendment; no product requirement changes silently.

All sample amounts are illustrative fixtures. No production service, database, OAuth application, CI workflow or payment has been created by writing these pages.