0pt/docs/09-build-plan.md

09 · Build plan

Phased, in dependency order. Finish a phase to its acceptance criteria before the next. Each phase = small, reviewable commits. Reconcile with existing code rather than rewriting wholesale.

Phase 0 — Foundation & repo

• Monorepo structure (docs/08). Migrate existing src/orchestrator + src/workers into services/api.
• Postgres schema + migrations (docs/03); pgvector enabled. .env.example.
• docker-compose up (postgres, redis, api, worker, nocodb, metabase, caddy). /health green.
• CI skeleton (lint/typecheck/build).
• Accept: docker compose up runs the whole stack locally; migrations apply; /health returns ok for db + queue.

Phase 1 — Design system in code

• Tailwind + shadcn; globals.css (grain + reveal keyframes) and useReveal verbatim (docs/05).
• Build DataArtifact primitive (table/map/schema/chart/grid) and ProvenanceBadge (docs/design prompts 5.1, 2.11).
• Accept: a sample page renders mono tokens, a DataArtifact animates on scroll, reduced-motion respected, focus rings visible.

Phase 2 — Marketing + catalog (placeholder data)

• Landing components top-to-bottom (build-brief 2.1–2.10): Header, Hero, Philosophy, Catalog teaser, Engine, Visualisation gallery, Coverage, Editorial, Proof, Footer.
• Full Catalog page + Dataset detail + Sourcing-map page (coverage doc 5.4). Postgres full-text search.
• All with loading/empty/error states + mobile.
• Accept: marketing site + catalog browse work end-to-end on placeholder catalog rows; one continuous scroll reads well; DoD met per screen.

Phase 3 — Auth & portal shell

• Auth.js + Postgres adapter; sign in/up/verify/forgot. orgs/users.
• Portal shell + Dashboard ("Mina beställningar") with empty state.
• Accept: a user can sign up, land in an empty dashboard, sign out; routes protected.

Phase 4 — Order lifecycle end-to-end (test mode)

• Configurator (2.12) wired to POST /estimates (real estimate math in FastAPI).
• Deposit checkout (2.13) → Stripe test Checkout → webhook → order IN_PRODUCTION.
• Production tracker (2.14) reading GET /orders/{id}/events (SSE) — pipeline may be simulated at this phase.
• Validation & delivery (2.15): tabs render from a sample delivery; accept → POST /payments/release (test) → DELIVERED; revise leaves escrow untouched.
• AI-assist (POST /ai/parse) prefilling the configurator.
• Accept: a full custom order can be configured, deposit paid (test), watched, validated, accepted, and "delivered" — state machine in docs/01 traversed; escrow split correct.

Phase 5 — Real data engine (Nordic slice)

• Compliant connectors first: GLEIF + Brreg + Companies House (verify access terms; record in sources.yaml). Remove any FlareSolverr/bypass path (docs/06).
• Pipeline stages produce real dim_company + fact_financials with bridge_provenance; QA threshold drops low-confidence rows.
• Production tracker now reflects real job metrics.
• Accept: a Nordic company dataset is produced for a real order, every field has provenance, quality report generated, level-0 fields shown honestly (not fabricated).

Phase 6 — Delivery surfaces & integrations

• Exports: CSV / Parquet / JSON via R2 presigned URLs.
• Embedded NocoDB ("Min data") and Metabase dashboards via signed URLs in mono chrome.
• Integrations: FiveCRM push, webhooks, Google Sheets.
• File uploads (Uppy → R2) for matching/enrichment.
• Accept: a delivered dataset is downloadable, viewable in embedded NocoDB + Metabase (no separate login), and pushable to FiveCRM; uploads work.

Phase 7 — Subscriptions / feeds

• subscriptions; recurring jobs (weekly/daily) delivering deltas; webhooks on change.
• Freshness monitoring; Resend emails (confirmation, "din data är klar", feedback).
• Accept: an order converts to a feed; a scheduled run produces a delta + fires a webhook + email.

Phase 8 — Admin, hardening, compliance

• Admin: order queue + scope/quote + escrow release; source registry & freshness monitoring; worker/job monitoring; customer + catalog management.
• Customer DB-access grant flow (encrypted, read-only, time-boxed) + revoke.
• Security pass: RLS, presigned-only files, signed embeds, secret rotation, audit_log everywhere; DPA published; legal pages.
• Finalize all loading/empty/error states + mobile across the app.
• Accept: admin can run the business; DB-grant flow works and self-revokes; security checklist passes; DoD met app-wide.

Phase 9 — Launch

• Domain 0pt.app (Vercel) + subdomains (api/data/dash via Caddy). Sentry + uptime live.
• Soft launch: Protosell internally + a handful of existing dealer relationships.
• Accept: a real external customer completes an order start→delivery in production; feedback loop running.

---

Working conventions (for Claude Code)

• Tech docs + identifiers English; UI copy Swedish.
• Conventional Commits; one concern per PR; keep diffs reviewable.
• No secrets in code; update .env.example when adding env.
• Add/extend tests for engine logic (estimate math, fusion/confidence, dedup) and API contract.
• When a source's access/licence is unclear, verify and record in sources.yaml before relying; if disallowed for bulk, route to licensed/partner or mark level 0 — never bypass, never fabricate.
• Touch the design tokens/motion only via docs/05; keep red ≤ once per screen; no photography.
• If anything here conflicts with existing code, flag it in the PR description and propose the reconciliation rather than guessing.