oO/PLAN.md

Implementation plan

Step-by-step build order for Phase 0 (walking skeleton) and the seams that make Phases 1–5 cheap.

The principle: build the contracts first, stub the internals. Every module exposes its contract and a /health story before any module is "finished". End-to-end walking skeleton in the first week.

Packaging reminder (ADR-0003): Phase 0 is a modular monolith — one Node process bundles services/* behind their HTTP contracts, plus ml/serving as a separate Python process. Contracts are identical whether the call is in-process or over the wire.

---

Stage 0 — Foundations (days 1–3)

1. Monorepo tooling. pnpm workspaces for TS; uv for Python; turbo for build graph; pre-commit (eslint, prettier, ruff, mypy, typecheck).
2. Docker Compose dev env with profiles:
   • core — Node monolith + ml/serving stub + Postgres.
   • full — adds NATS, MinIO, MailHog. Needed from Stage 4 onward.
3. CI skeleton (Gitea Actions): lint → typecheck → unit → build → publish images. Schema-registry check for protobuf events (added in Phase 1, but pipeline stub now).
4. Secrets convention. .env.example per module; prod injected by orchestrator.
5. Shared types. OpenAPI for HTTP, protobuf for events (ADR-0005). Generate TS; Python pydantic models hand-written initially (few consumers).
6. Import-boundary lint. eslint-plugin-boundaries (or equivalent) prevents services/integrations from importing services/recommender internals. Contracts-only.

Exit: docker compose --profile core up brings a green dashboard of /health endpoints.

Stage 1 — Identity & session (days 4–7)

1. services/auth module: Auth.js embedded in the Node monolith, Google provider only (Apple deferred). OIDC-shaped surface (ADR-0004): /me, /logout, JWKS, stub /.well-known/openid-configuration.
2. services/profile module: User row created on first sign-in; consent record captured with ToS/PP version hash.
3. apps/web sign-in page. Gateway (also in-process) verifies JWT.
4. Deletion endpoint (yes, already): DELETE /me — revokes sessions, flips deleted_at, emits user.deletion_requested.

Exit: a user can sign in, see their profile, and delete their account; deletion is observable end-to-end even though there's no data to erase yet.

Stage 2 — Integrations framework (days 8–12)

1. services/integrations module with a Connector interface:
   • beginOAuth(user) → {redirectUrl, state}
   • finishOAuth(code, state) → StoredCredential
   • fetchSignals(user, since?) → AsyncIterable<NormalizedEvent>
   • act?(user, action) → void
   • revoke(user) → void — first-class; no revocation means no disconnect.
2. Token vault: libsodium sealed box, key from env/KMS. One row per (user, provider) with provider-specific meta (e.g. Todoist sync_token).
3. Todoist connector: OAuth2, Sync API incremental reads via sync_token, act to complete a task, revoke calls Todoist's token-revocation endpoint.
4. Web /connect: list of connectors, per-connector consent screen (scopes + retention), connect/disconnect.

Exit: a user can connect and disconnect Todoist; disconnect revokes at Todoist and wipes local credentials.

Stage 3 — Recommender contract (days 13–16)

1. services/recommender module exposes POST /recommend and POST /feedback.
2. Policy registry keyed by name. Candidate sources registered independently; v0 source = integrations.todoist.tasks.
3. RandomPolicy v0 — draws uniformly.
4. Tip shape provider-agnostic: {id, kind: "todo"|"advice", title, body, source, deep_link, meta}.
5. TipInstance persisted with context_snapshot — the features-seen-at-decision-time blob that makes offline replay possible later.
6. apps/web tip page:
   • kind=todo → tap = done (calls integrations.todoist.act(complete)).
   • kind=advice → tap = acknowledge; long-press = save.
   • Snooze / dismiss via long-press menu regardless of kind.
   • Every reaction emits a feedback event even though it's in-process today.

Exit: three-page prototype works end-to-end.

Stage 4 — Hardening (days 17–20)

1. Observability: pino + structlog, Sentry per module, W3C traceparent across the monolith boundary and into ml/serving.
2. Rate limits, retries with jitter, and circuit breakers on outbound (Todoist, Google).
3. Integration tests: Playwright for the web flow (sign-in → connect → tip → delete). Contract tests between modules so the extractions later are safe.
4. Metrics baseline wired (docs/architecture/metrics.md): activation, first-tip reaction, dwell, snooze:dismiss ratio, D1 retention.
5. Deploy to a single VM via docker-compose + Caddy; Caddy auto-TLS; healthchecks wired to Caddy.

Exit: Phase 0 milestone closed; real users can be onboarded.

---

Seams prepared for later phases (designed now, implemented later)

• Event bus abstraction. emit(event) / subscribe(topic, handler) today is in-process; the production implementation in Phase 1 is NATS JetStream. Callsites never change.
• Feature assembler. Recommender accepts a context blob from a FeatureAssembler; in Phase 0 it returns a hard-coded minimum; in Phase 1 it calls the feature store.
• Shadow-policy hook. The recommender already supports running N policies in shadow per request; v0 runs zero shadows but the hook exists.
• Extraction-ready modules. Every services/*/ has a serve.ts that can be mounted in the monolith or booted standalone. Dockerfile targets both.

---

Staffing assumption

Three parallel streams: platform (infra, CI, shared-types), backend (auth, profile, integrations, recommender), web (sign-in, connect, tip, PWA). ml joins in Phase 1. Each Gitea issue carries its stream label and milestone.