chore: scaffold oO monorepo with architecture, roadmap, and module stubs

PLAN.md

@@ -0,0 +1,71 @@
+# Implementation plan
+
+Step-by-step build order for Phase 0 (prototype) and the seams that make Phases 1–5 cheap.
+
+The principle: **build the contracts first, stub the internals.** Every service should exist with a `/health` endpoint and a minimal real implementation of its interface before any service is "finished". This gives us an end-to-end walking skeleton from week one.
+
+---
+
+## Stage 0 — Foundations (days 1–3)
+
+1. **Monorepo tooling.** pnpm workspaces for JS/TS; uv or poetry for Python; turbo or nx for build graph; pre-commit (lint, typecheck, format).
+2. **Docker Compose dev env.** Postgres, NATS, MinIO (S3), Mailhog, all services wired with hot-reload.
+3. **CI skeleton** (Gitea Actions): lint → typecheck → unit test → build → publish images.
+4. **Secrets convention.** `.env.example` per service; prod secrets injected by orchestrator.
+5. **Shared types package.** OpenAPI source → generated TS + Python clients.
+
+Deliverable: `docker compose up` brings a green dashboard of `/health` endpoints.
+
+## Stage 1 — Identity & session (days 4–7)
+
+1. `services/auth`: Google OAuth2 (PKCE), session cookies, short-lived JWTs, refresh rotation. Library-backed (Auth.js or Ory Kratos + Hydra) — we do not roll our own.
+2. `services/profile`: minimal `User` record; created on first sign-in.
+3. `apps/web` sign-in page; gateway verifies JWT.
+
+Exit check: a user can sign in and fetch their own profile.
+
+## Stage 2 — Integrations framework (days 8–12)
+
+1. `services/integrations` with a **Connector** interface:
+   - `begin_oauth(user) → redirect_url`
+   - `finish_oauth(code, state) → StoredCredential`
+   - `fetch_signals(user, since) → Event[]`
+2. **Token vault**: column-level encryption (libsodium), key from env or KMS.
+3. **Todoist connector** as the first concrete implementation.
+4. Web "Connect" page: list of connectors, button per connector, callback handling.
+
+Exit check: a user taps "Connect Todoist", completes the OAuth dance, and the integrations service can fetch their tasks on demand.
+
+## Stage 3 — Recommender contract (days 13–16)
+
+1. `services/recommender` exposes `POST /recommend {user_id, context} → {tip}`.
+2. Policy interface (`Policy.pick(user, candidates, context) → tip`).
+3. **`RandomPolicy` v0** — fetches candidates from `integrations` (Todoist tasks), returns one uniformly at random.
+4. Tip shape is provider-agnostic: `{id, kind: "todo"|"advice", title, body, source, deep_link, meta}`.
+5. `apps/web` tip page: full black, one tip centered, tap = mark done → callback fires to integrations (complete Todoist task) + emits a feedback event.
+
+Exit check: three-page prototype works end-to-end for one user.
+
+## Stage 4 — Hardening the prototype (days 17–20)
+
+1. Error surfaces (Sentry), structured logs (pino / structlog), trace IDs across services.
+2. Rate limits + retries on outbound API calls.
+3. Integration tests: Playwright for the web flow, pact-style contract tests between services.
+4. Deploy to a single VM via docker-compose + Caddy.
+
+Exit check: Phase 0 milestone closed.
+
+---
+
+## Seams prepared for later phases (do not implement yet, but do not foreclose)
+
+- **Event bus.** From day one, `integrations` and `recommender` speak through an async fn that today is an in-process call but will be NATS tomorrow. Keep the signature `(event: NormalizedEvent) → void`.
+- **Feature store.** The recommender accepts a `context` blob; later, a feature service fills it. Do not inline feature lookups inside the policy.
+- **Policy registry.** `PolicyFactory.get(name)` so A/B and bandit policies slot in without code changes to the gateway.
+- **Python boundary.** Recommender is TS today, but its scoring function is isolated — moving to FastAPI in Phase 1 is a file move, not a refactor.
+
+---
+
+## Staffing assumption
+
+Work is parallelizable across ~3 streams: **infra/platform**, **backend services**, **web app**. Each Gitea issue notes which stream and which phase (milestone) it belongs to.