spb/cancerindex

1# CancerIndex.io — the global index of cancer23CancerIndex is a provenance-first, continuously updated, transparently sourced oncology knowledge4platform. It connects a canonical cancer ontology (NCIt-anchored, OncoTree and registry dimensions)5to epidemiology, genomics, biomarkers, therapies, clinical trials, regulatory evidence and literature6— for every recognised malignant disease entity — and publishes reproducible rankings with their7scope, formula version and lineage down to the raw record.89It is not a physician, not a diagnostic tool, and gives no treatment recommendations.1011## Status1213Phase 1 (2026-09). Foundation, connectors, public API, worker and web app are being built in14parallel. Data currently ingested locally: OncoTree (865 cancer entities), with NCIt EVS, HGNC,15CIViC, GDC, ClinVar, ClinicalTrials.gov, PubMed and CDC WONDER connectors in progress. GLOBOCAN16remains under license review and SEER awaits credentials — the platform says so rather than showing17numbers it cannot source.1819## Repository2021```22apps/web         Next.js 16 public site (port 8250), proxies /api/v1/* to the API23apps/api         Fastify 5 public API /v1 (port 8251), OpenAPI at /v1/docs24workers/         pg-boss scheduler: connector cron, counters, rankings, health probes25packages/        shared · database (Drizzle) · ontology · connectors (SDK + connectors) · ranking26scripts/ci.ts    operator CLI (pnpm cix …)27deploy/          MacLustr mld manifest, first-run bootstrap28docs/            architecture, data model, methodology, API, security, AI policy, ADRs, connector docs29```3031Start with `CLAUDE.md` (operational rules), then `docs/ARCHITECTURE.md`, `docs/DATA-MODEL.md` and32`docs/METHODOLOGY.md`.3334## Quickstart3536Requirements: Node ≥ 22, pnpm 11, PostgreSQL 17 with `pg_trgm`, `unaccent` and `vector`.3738```bash39createdb cancerindex && cp .env.example .env      # set NCBI_EMAIL, ADMIN_TOKEN40pnpm install41pnpm db:migrate && pnpm db:seed && pnpm cix sources:sync42pnpm cix run oncotree --mode dry_run              # smoke test against the live API (no writes)43pnpm cix run oncotree                             # first real ingest44pnpm cix counters && pnpm cix rank45pnpm dev:api &                                    # http://127.0.0.1:8251/v1/docs46pnpm worker &                                     # schedules from connector manifests47pnpm dev:web                                      # http://localhost:825048```4950Verify: `curl -s localhost:8251/healthz`, `curl -s "localhost:8251/v1/search?q=glio"`.5152## CLI5354```55pnpm cix connectors                 list connectors, license status, health56pnpm cix run <id> [--mode full|incremental|dry_run] [--max-records N] [--max-minutes M] [--reset-cursor]57pnpm cix run-all [--max-minutes M]  every active connector in registry order58pnpm cix health <id>                source liveness probe59pnpm cix sources:sync               manifests → sources table60pnpm cix counters                   rebuild entity_counters61pnpm cix rank                       recompute ranking snapshots62pnpm cix stats                      table counts63pnpm cix trace <table> <id>         lineage of a value6465tsx workers/cli.ts run <id> | counters [--then-rank] | rank | health | schedules | queues66pnpm --filter @cancerindex/api create-key -- --label "Lab" --tier research --rpm 60067```6869## Quality gates7071```bash72pnpm typecheck        # every workspace73pnpm -r test          # vitest; connector tests use fixtures, API smoke tests skip without a DB74```7576## Deployment7778Production runs on the MacLustr cluster through `mld` (gateway M1M32): manifest79`deploy/mld-manifest.cancerindex.json`, `mld stage <dir> cancerindex`, `mld deploy cancerindex`,80then `deploy/first-run.sh` for the ordered first ingestion. PM2 processes `cancerindex-web`,81`cancerindex-api`, `cancerindex-worker`; ngrok `www.cancerindex.io` → 8250. See `deploy/README.md`.8283## Principles (short form)84851. No scientific number without provenance; derived values carry a formula version and inputs.862. Layers stay separable: RAW → NORMALIZED → CANONICAL → DERIVED → RANKED → AI.873. Never fake data: missing is missing ("Data not yet available"), never zero.884. Identifiers are first-class: every upstream id is kept; public ids are `CI-<NS>-00000001`.895. Reconciliation before ingestion; unknown labels go to a curation queue, never dropped.906. Time-aware observations: a new year is a new row.917. Every edge has context: cancer, direction, evidence level, provenance.928. Licensing gate on every source; scientific safety labels are never merged.9394## License and attribution9596Code: private (Groupe/SPB). Data: each source keeps its own license and attribution, surfaced in97every API response (`sources`) and on `/sources`. See `docs/source-policy.md`.98