0pt/docs/02-architecture.md

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.