Trace — Curve Digitization Platform

Governed, searchable store for digitized curves extracted from published clinical and scientific figures. Royalty Pharma's research analysts submit conforming ZIP archives; Trace ingests them atomically with full provenance, validates them through a review workflow, and makes the corpus searchable and exportable.

Status: Build complete — all sessions S01–S08 delivered and signed off.

---

Stack

Layer	Technology	Hosting
Frontend	Next.js (React)	Vercel
Backend	FastAPI (Python 3.12)	Railway
Database	PostgreSQL	Neon
Object store	Vercel Blob (fallback: Backblaze B2)	—

---

Local Development

Prerequisites

• Python 3.12 + uv
• Node.js 20+
• PostgreSQL (local or Neon connection string)

Backend

cp .env.example .env
# fill in DATABASE_URL_RUNTIME, DATABASE_URL_DEPLOY, JWT_SECRET, BLOB_TOKEN, BLOB_ENDPOINT

make migrate   # run Alembic migrations
make dev       # uvicorn on :8000 with --reload

Frontend

cd frontend
cp .env.example .env.local
# set NEXT_PUBLIC_API_BASE_URL=http://localhost:8000

npm install
npm run dev    # Next.js on :3000

Other commands

make test      # pytest
make lint      # ruff

---

Environment Variables

See .env.example for all required variables. Key ones:

Variable	Description
DATABASE_URL_RUNTIME	asyncpg URL — FastAPI runtime connection
DATABASE_URL_DEPLOY	psycopg2 URL — Alembic migrations and seed scripts
JWT_SECRET	Long random secret for JWT signing
BLOB_BACKEND	vercel_blob or b2
BLOB_TOKEN	Vercel Blob store token (from Vercel dashboard)
BLOB_ENDPOINT	CDN base URL from the same Blob store
ALLOWED_ORIGINS	JSON array of allowed CORS origins

---

Backend Modules

Module	Responsibility
auth	JWT persona selector — Analyst, Validator, Admin
type_registry	Curve type definitions and extensible plot-type registry
vocabulary	Controlled endpoint vocabulary (read-only at runtime)
ingest	Atomic ZIP submission ingestion (INV-01)
validation	Validator accept/reject workflow
correction	Post-acceptance curve correction
search	Corpus search by any supported axis
export	CSV export
submission_history	Full provenance trail per submission
storage	Blob backend abstraction (Vercel Blob / B2)
common	Shared models, exceptions, permission model

---

Repository Structure

Path	Purpose
backend/	FastAPI application, Alembic migrations, pytest suite
frontend/	Next.js application
tools/	Shell automation scripts (challenge, resume, monitor, launch)
brief/	Client requirements briefs — never modified after receipt
docs/	PBVI planning artifacts (ARCHITECTURE.md, INVARIANTS.md, EXECUTION_PLAN.md, Claude.md)
sessions/	Per-session logs and verification records (S01–S08)
verification/	Formal sign-off checklists
discovery/	BCE close-out artifacts (TOPOLOGY.md, MODULE_CONTRACTS.md, SYSTEM_GRAPH.json, etc.)
enhancements/	Enhancement registry and per-enhancement packages

---

Key Documentation

If you want to…	Read
Understand the system design	docs/ARCHITECTURE.md
Understand the constraints	docs/INVARIANTS.md
Understand the AI execution contract	docs/Claude.md
Understand the build history	sessions/
Understand the system intelligence layer	discovery/INTAKE_SUMMARY.md
Work on an enhancement	enhancements/REGISTRY.md
See the full file registry	PROJECT_MANIFEST.md

---

Rule Compliance

• Rule 1: All file references use full paths from repo root — never bare filenames.
• Rule 2: All files inside any enhancement package carry their ENH-NNN prefix — no exceptions.
• Rule 3: Any file not registered in PROJECT_MANIFEST.md must not be read by CC as authoritative input.