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

9.0 KiB

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.