# 02 · Architecture ## Principle: one database, many lenses Postgres is the source of truth. Everything else is a **lens** on it. A tool enters the stack only if it (a) reads that Postgres and (b) sits behind the same auth. This is the difference between an app and a pile of separate logins. ``` ┌──────────────────────────────────────────────┐ COLLECTION │ POSTGRES │ LENSES (customer + admin) (legal engine) │ dim_company · dim_contact · dim_vehicle │ ─────────────── │ fact_financials · dim_ubo │ ───────────────────────────── Official APIs │ dim_source · bridge_provenance │ Next.js portal (Vercel) /bulk ───────▶│ orders · order_items · jobs · deliveries │◀── Catalog + order lifecycle Authorized web │ subscriptions · users · orgs · files │ NocoDB (embedded "Min data") Licensed data │ db_grants · audit_log · pgvector embeddings │ Metabase (embedded dashboards) Customer upload│ │ Export: CSV/Parquet/JSON/API/FiveCRM └───────────────────▲──────────────────────────┘ │ FastAPI orchestrator + workers (estimates, orders, jobs, AI-assist, webhooks, pipeline) ``` ## Components & responsibilities - **Next.js (Vercel)** — all customer/admin UI: marketing site, catalog, configurator, checkout, production tracker, validation, portal, admin. Calls FastAPI over an internal token. Embeds NocoDB/Metabase via signed URLs (no separate login shown). - **FastAPI orchestrator** (`src/orchestrator`) — REST contract in `docs/04-api.md`: estimates, orders, AI-assist, uploads, deliveries, webhooks, catalog, sources, job status/SSE. **Not on Vercel** (serverless timeouts kill long jobs). - **Workers** (`src/workers`) — adaptive router + pipeline stages (sourcing → extraction/OCR → structuring → enrichment/fusion → QA). Write to Postgres with provenance. See `docs/06-data-engine.md`. - **Postgres** — backbone (`docs/03-data-model.md`) incl. `pgvector` for matching/embeddings. - **NocoDB** — Airtable-style views over existing tables (no data duplication). Embedded into portal as "Min data". - **Metabase** — customer-facing dashboards. Embedded. - **Cloudflare R2** — file storage (uploads + deliverables) via presigned URLs. - **Stripe** — deposit capture + escrow balance release. - **Resend** — transactional email (order confirmation, "din data är klar", feedback). - **Auth.js** (NextAuth) with a Postgres adapter — single auth for the whole app; NocoDB/Metabase hidden behind it. ## Stack decisions — IN | Concern | Choice | Why | |---|---|---| | Frontend | Next.js App Router + TS + Tailwind + shadcn/ui | Vercel-native, matches existing skills | | Backend/jobs | FastAPI + workers (existing) | already built; long-running jobs | | DB | Postgres (+ pgvector) | backbone; Neon free tier or on-VPS | | Airtable layer | **NocoDB** | sits on existing tables, no duplication | | BI | **Metabase** | customer-facing embedding, simple | | Files | Cloudflare R2 + presigned URLs | cheapest S3-compatible | | Payments | Stripe Checkout + webhook → FastAPI | ~1 day, no SaaS boilerplate needed | | Auth | Auth.js + Postgres adapter | one system | | Email | Resend | best Next.js integration, free tier | | Quality | Great Expectations / checks **inside workers** | scores shipped with each order | ## Stack decisions — OUT (do not add) | Rejected | Reason | |---|---| | Superset | Metabase already covers BI — one tool, not two | | DataHub / OpenMetadata | enterprise-heavy; catalog = a Postgres table in Next.js + NocoDB. Add lineage only if an enterprise customer demands it | | Baserow / Teable | NocoDB chosen — not three Airtable clones | | Meilisearch (v1) | Postgres full-text suffices to a few thousand rows; add later | | Delta Sharing (v1) | unnecessary; customer pull via scoped role + exports | | Trigger.dev | the existing queue already schedules jobs; Resend covers mail | | FlareSolverr / stealth browsers / undetected-* / proxy-fingerprint rotation / fake-account creation | **prohibited** — see CLAUDE.md §1. Replace with compliant fetching | ## Hosting (cheapest coherent) - **Vercel** (Hobby/free) — Next.js + custom domain `0pt.app`. - **One small VPS** (e.g. Hetzner ~€5/mo) running `docker-compose`: FastAPI, workers, NocoDB, Metabase, (Postgres or use Neon), optional Meilisearch later. Per-service managed platforms (Railway) get expensive once you have 4–5 always-on services; a single VPS + Vercel + R2 lands ≈ <€10/mo to start. - **Cloudflare R2** — object storage. - **Postgres** — on the VPS, or **Neon** free tier if you want it managed. Full config, env, security, CI/CD: `docs/08-infrastructure.md`.