0pt/CLAUDE.md

CLAUDE.md — 0pt (SIAX Technology AB)

Read this first. It is the contract for how this project is built. Then read docs/ in order.

What 0pt is

0pt — your data. A Nordic/European data-services platform (0pt.app) where customers:

1. Compose a data job (markets, entity type, fields, enrichment, frequency, output) — or browse ready-made datasets.
2. Pay a 50 % deposit to start; the remaining 50 % is held in escrow and released only on approval.
3. Watch production live (sourcing → extraction → structuring → enrichment → QA).
4. Validate the result with full freedom (table / map / schema / quality views) and deliver to any format/destination.

Owned by SIAX Technology AB. Feeds internal products too (Protosell/FiveCRM, VehIQ).

Non-negotiable constraints (do not violate)

1. Legal sourcing only. The data engine uses, in strict priority: official APIs/bulk → authorized scraping of clearly public pages (respect robots.txt + rate limits) → licensed partner data → otherwise the field is delivered as "not available / licensed only". We never invent values.
   • Do NOT build, keep, or extend: WAF/bot-detection bypass (incl. FlareSolverr, "stealth" browsers, undetected-* used to defeat detection), fingerprint/proxy rotation to evade bans, scraping behind login walls, or automated fake-account creation (Apollo etc.).
   • If existing code (e.g. src/workers/browser_worker.py) contains a FlareSolverr/bypass path, remove or disable it and replace with compliant fetching. This is a product-positioning + compliance requirement, not a preference. "Honest accuracy" is the whole moat.
2. Postgres is the backbone. One Postgres is the source of truth. Catalog, portal, NocoDB views, Metabase dashboards, workers, exports all read/write the same DB. A tool may only enter the stack if it (a) reads that Postgres and (b) sits behind the same auth.
3. Provenance per field. Every fact carries source, freshness, confidence (bridge_provenance). This drives the UI signature too.
4. One tool per job. Do not add overlapping tools. The approved stack is in docs/02-architecture.md and docs/07-dependencies.md. Anything not listed needs a documented reason.
5. GDPR-native. DPA, lawful basis, audit log, deletion-after-job. Customer DB access is pull by the customer via a read-only, time-boxed role they create — never us asking for admin, never raw creds stored in plaintext.
6. Design is fixed. Mono/editorial system (white #fff, text #0a0a0a, hairline #e5e5e5, radius 0, Inter + JetBrains Mono, single red #e40014). Exact tokens + motion in docs/05-design-system.md. No photography — imagery is rendered data (DataArtifact).

Build on existing code

A working repo already exists (~145 files): FastAPI orchestrator (src/orchestrator/main.py, 25+ endpoints), workers (src/workers/: adaptive_router, browser_worker, ocr_worker, db), and country data for 20 markets. Reconcile with it, don't blindly replace. Where this documentation defines a target contract, migrate the existing code toward it. Flag conflicts instead of guessing.

How to work

• Work in dependency order per docs/09-build-plan.md. Finish a phase to its acceptance criteria before the next.
• Small, reviewable commits. Conventional Commits (feat:, fix:, docs:, chore:).
• Frontend = Next.js App Router + TS + Tailwind + shadcn/ui on Vercel. Backend = FastAPI + workers, not on Vercel (long jobs).
• Tech docs + code identifiers in English; all visible UI copy in Swedish.
• Never hardcode secrets — use env (docs/08-infrastructure.md).
• When unsure about a source's current access/licence terms, verify before relying on it and record it in the sourcing map; do not assume.

Documentation index

Doc	Purpose
docs/01-product.md	Vision, the three flows, order lifecycle, business model
docs/02-architecture.md	System architecture, stack decisions (in/out), hosting
docs/03-data-model.md	Postgres schema, provenance model, migrations
docs/04-api.md	FastAPI contract (canonical endpoints)
docs/05-design-system.md	Mono tokens, motion, visual system, signature
docs/06-data-engine.md	Workers, legal sourcing chain, pipeline, QA, fusion, sources.yaml
docs/07-dependencies.md	Repos/libraries to import (+ explicit exclusions)
docs/08-infrastructure.md	Hosting, docker-compose, env, security, CI/CD
docs/09-build-plan.md	Phased milestones with acceptance criteria
docs/design/0pt-v0-build-brief.md	Per-component v0 prompts (design reference)
docs/design/0pt-design-coverage-and-visuals.md	Full page/component inventory + visual system

Definition of done (every screen, before real data)

Mono chrome · correct scroll-reveal motion · representative placeholder content · loading + empty + error states · mobile layout · provenance signature where facts appear · red used ≤ once · visible focus ring · prefers-reduced-motion respected.