Files
0pt/CLAUDE.md
T
opt-vehiq-work salvage 1d63f63dfd
CI (SIAX Cloud) / quality (push) Successful in 49s
CI (SIAX Cloud) / security (push) Successful in 7m5s
Security Scan (SIAX Cloud) / security (push) Successful in 7m5s
CI (SIAX Cloud) / integration (push) Successful in 18m53s
CI (SIAX Cloud) / security (pull_request) Successful in 46s
Security Scan (SIAX Cloud) / security (pull_request) Successful in 58s
CI (SIAX Cloud) / integration (pull_request) Successful in 1m38s
CI (SIAX Cloud) / quality (pull_request) Successful in 1m45s
chore(salvage): preserve uncommitted WIP from /opt/vehiq-work/0pt-p060-p068_0pt before machine cleanup (2026-09-27)
This snapshot was found sitting uncommitted in a stale /opt/vehiq-work
lane clone dated ~2026-09-09..18, base branch: feat/p060-p068-ingestion-plane.
Not reviewed, not verified against current main. Pushed only so the
directory could be deleted without losing the diff.
2026-09-27 12:58:50 +02:00

68 lines
9.0 KiB
Markdown

# 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. **Sourcing and egress boundary.** The data engine prioritizes official APIs/bulk, configured public-web collection and partner data, and never invents values. Proxy routing is not implemented locally.
- **Capability-neutral rule:** no technical function category is blanket-prohibited or deleted. Proxy rotation, stealth browser, managed unblock and other high-risk modes are modeled as explicit, optional 1p capabilities with CL0UD entitlement, destination scope, isolation, budget and audit. 0pt consumes those contracts through b0ts/1p instead of building a second provider router or holding providercredentials.
- **Verified historical state:** no `src/workers/browser_worker.py` exists; the active engine workers live under `services/api/workers/`. This checkout also contains the older `services/scrapers/*` stack. Do not describe it as removed or as the new 1p implementation. Preserve it until a scoped migration, prevent new product paths from depending on it, and move active network ownership to b0ts + 1p.
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 engine repo already exists. **Corrected this pass — the previous description of it was wrong on every specific:** the FastAPI orchestrator lives at `services/api/orchestrator/main.py` (not `src/orchestrator/main.py`) and registers **12** route handlers (not "25+"); the workers directory is `services/api/workers/` and contains `adaptive_router.py`, `pipeline.py`, `queue.py`, `resolve.py`, and `run.py` (not `browser_worker`/`ocr_worker`/`db` — none of those three files exist anywhere in this repo); and `services/api/sources/sources.yaml` currently covers **7** markets (`SE`, `NO`, `DK`, `FI`, `GB`, `NL`, plus `global`), not 20. `services/api/` holds 11 Python source files total (excluding `__pycache__`). **Reconcile with the code as it actually is, not this description's prior claims.** Where this documentation defines a target contract, migrate the existing code toward it. Flag conflicts instead of guessing.
**Two remotes claim to be this repo, and it's unresolved which is authoritative.** `origin` here is `github.com/sax3l/0pt`. A separate Gitea remote, `git.siax.io/sax3l/0pt`, shares at least part of the same history but has independently diverged (see README "Known issues" for specifics). Do not assume `origin` is the only copy of this codebase, and do not silently resolve the question of which is canonical — that is Simon's decision.
**Before trusting any status claim in this doc corpus, read README's "Known issues" section.** It covers the auth/tenant-scoping gap, the platform-client mock-only status, and the underlying fact that 0pt's quality-check/QA enforcement code was never built despite once being described as real. **Corrected this pass:** `docs/ICEBERG_WRITE_BOUNDARY.md`, `docs/11-lakehouse-write-plan.md`, and `docs/P0_QUERY_SOURCE_FLOW.md` are now all consistently corrected — each carries its own "fabricated, not built" callout and none asserts `quality-check-service.ts`/`quality-report-service.ts`/etc. as real or tested anywhere in its current body (verified this pass by reading all three in full). `docs/P0_DATASET_QUALITY_FLOW.md` remains the explicit target-spec replacement for what that stage should look like once built. Treat any *other* doc claiming the QA stage already exists as wrong.
## 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 the SIAX Deploy Platform. Backend = FastAPI + workers on a VPS (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/10-lakehouse-decision.md` | Pointer to an ecosystem-wide lakehouse ADR made outside this repo (Apache Iceberg = canonical SIAX lakehouse format, ADR-0030 in the `n0d` repo; 0pt = write-path owner). Does not change `docs/02`/`docs/03` |
| `docs/11-lakehouse-write-plan.md` | 0pt's own follow-up task list for the Iceberg write boundary — schema/event names for the implementation. **Corrected**: item 4 (quality rules) is explicitly labeled NOT BUILT, and the old fabricated `quality-check-service.ts`/`quality-report-service.ts` claim is quoted only inside its own "Correction" callout, never asserted as fact |
| `docs/12-edge-capability-api.md` | Edge-native TypeScript P0 capability API contract (`app/api/0pt/*`, `/api/screen`, `/api/ai/parse`) — distinct from `docs/04-api.md`'s FastAPI-engine contract; documents several confirmed always-fails-over-HTTP routes and the tenant_id/in-memory gaps |
| `docs/ICEBERG_WRITE_BOUNDARY.md` | Implementation record + "real vs. contract-only" verification status: dataset<->Iceberg-table mapping and source-rate-policy contracts, ST0RE lakehouse client, and the 2026-07-13 **live-verified** write path (real namespace/table/snapshot IDs). **Corrected**: its "Data quality: not yet built" section explicitly quotes and retracts the old fabricated claim rather than repeating it as fact |
| `docs/P0_QUERY_SOURCE_FLOW.md` | `0pt.query_source` bounded source-query flow — **corrected**: no longer claims `quality-check-service.ts` exists, now points at the real precedent (`iceberg-write-service.ts`) instead |
| `docs/P0_DATASET_QUALITY_FLOW.md` | An explicit **target-spec-only, not-yet-built** replacement for the fabricated quality-check/QA claims — read it as "should", never "does" |
**Corrected:** this table previously listed `docs/design/0pt-v0-build-brief.md` and `docs/design/0pt-design-coverage-and-visuals.md` as if they existed. They do not — confirmed via a full-repo search, including after this unification merge; there is no `docs/design/` directory at all. No `docs/` design-brief content is fabricated here to fill the gap. Either write those two docs or stop referencing them; until one of those happens, treat any prior claim that they exist as false.
## 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.