Hero is now a data-native 0pt artifact (no photos, keeps grain/reveal/float); header is the 0pt wordmark with Swedish nav; layout is sv + loads JetBrains Mono + 0pt metadata; globals wires the loaded fonts. Adds CLAUDE.md + docs/01-09 as the build contract. next build green (5 routes). Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
71 lines
5.1 KiB
Markdown
71 lines
5.1 KiB
Markdown
# 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`.
|