Files
0pt/docs/02-architecture.md
T
adminandClaude Opus 4.8 22e09d984d feat: rebrand MONO->0pt (hero, header, layout) + add project docs/contract
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>
2026-06-24 17:38:07 +02:00

71 lines
5.1 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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`.