Specifications

OpenOnco is a specifications-first project. Every architectural, clinical, and governance detail is pinned in a markdown document under specs/ that is versioned and open to public review. 10 active specifications cover everything from intended-use design constraints to the shape of every YAML entity in the KB. The full text lives at github.com/romeo111/OpenOnco/specs.

Source-of-truth hierarchy (from CLAUDE.md): when specs conflict, the binding order is 1. CHARTER.md → 2. other specs/*.md → 3. CLAUDE.md → 4. README.md. Anything under legacy/ is not authoritative.

Active specifications (10)

Governance CHARTER.md

Charter & Governance

Project governance, scope (what it does and what it explicitly does not), intended-use design constraints (§15 with constraints C1-C7), the solo-maintainer workflow for source-traceable content (§6.1), patient-data privacy (§9.3), forbidden prompt patterns for LLMs (§8.3 — LLMs do not make clinical decisions).

Read on GitHub → Raw markdown

Clinical CLINICAL_CONTENT_STANDARDS.md

Clinical Content Standards

Clinical content standards: citation format (source_id + position + paraphrase + page), evidence-level taxonomy (Tier 1-6), reviewer sign-off workflow, STUB → reviewed transition criteria. Every claim in an Indication / Regimen / RedFlag links to a Source entity.

Read on GitHub → Raw markdown

Data DATA_STANDARDS.md

Data Standards — Patient Model

Patient profile data model. FHIR R4/R5 + mCODE alignment on the roadmap. Code systems: LOINC + ICD-10/O-3 + RxNorm + CTCAE v5.0. No SNOMED CT and no MedDRA in the MVP (license gates). Profile fields and semantic interoperability.

Read on GitHub → Raw markdown

Schema KNOWLEDGE_SCHEMA_SPECIFICATION.md

Knowledge Schema Specification

Pydantic schemas for every KB entity — Disease / Indication / Regimen / Algorithm / Biomarker / Drug / Test / Workup / RedFlag / Contraindication / MonitoringSchedule / SupportiveCare / Source. Defines fields, validators, referential-integrity rules, and the migration roadmap to PostgreSQL.

Read on GitHub → Raw markdown

Sources SOURCE_INGESTION_SPEC.md

Source Ingestion & Licensing

How we ingest sources: the hosting matrix (referenced vs hosted vs mixed) with H1-H5 justification, license-classification gates, the add-a-source checklist (§8), the hosted-source checklist (§20), and the SourceClient protocol for live APIs.

Read on GitHub → Raw markdown

Testing REFERENCE_CASE_SPECIFICATION.md

Reference Case — "Patient Zero"

A synthetic HCV-MZL reference case as the P0 acceptance test. Defines every required patient-profile field (§2 templates), the critical structural assertions for Plan render output (§1.3), and milestones M1-M6 for expanding coverage.

Read on GitHub → Raw markdown

Engine MDT_ORCHESTRATOR_SPEC.md

MDT Orchestrator + Decision Provenance

Orchestrate_mdt rules (R1-R9 for treatment, D1-D6 for diagnostic), role activation logic (required / recommended / optional), the Open Questions mechanism (Q1-Q6 + DQ1-DQ4 — the engine refuses to decide without the required data), and a decision-provenance graph for audit-grade explanation.

Read on GitHub → Raw markdown

Engine DIAGNOSTIC_MDT_SPEC.md

Diagnostic-Phase MDT (Pre-biopsy)

Pre-biopsy mode: when histology is not yet available the engine emits a DiagnosticPlan with a workup brief instead of a treatment Plan. CHARTER §15.2 C7 hard rule. DiagnosticWorkup + DiagnosticPlan schemas, generate_diagnostic_brief(), polymorphic orchestrate_mdt with DQ1-DQ4 rules.

Read on GitHub → Raw markdown

Clinical WORKUP_METHODOLOGY_SPEC.md

Workup Research Methodology

How we build a basic workup for any oncology area. Source hierarchy (Tier 1: NCCN/ESMO/EHA/BSH/WHO/ASH), Test/Workup completeness checklists, the 7-step process for extending coverage to a new domain, anti-patterns.

Read on GitHub → Raw markdown

Engine SKILL_ARCHITECTURE_SPEC.md

Skill-Oriented Architecture (MDT Roles as Skills)

Formalises MDT roles (haematologist / pathologist / radiologist / etc.) as clinically-verified skills — each skill carries version, sources, last_reviewed, clinical_lead. Sizing horizon (~12-15 MVP → 50-60 comprehensive), 8-domain layout, 5-phase refactor plan.

Read on GitHub → Raw markdown

Regulatory source (PDF)

Regulatory PDF Guidance-Clinical-Decision-Software_5.pdf

FDA Clinical Decision Support Software Guidance

The official FDA guidance on non-device CDS classification under §520(o)(1)(E). Hosted under specs/ as a PDF. CHARTER §15 cites concrete criteria 1-4 from this document to justify OpenOnco's non-device positioning.

View PDF on GitHub →

How we update the specifications

Solo project. One maintainer delivers updates with automated checks and source traceability. External clinical review is optional and is recorded separately.

All specifications are written Ukrainian-first (the interface and the clinical reviewers are UA), but technical terms and license names stay in English inline. Versioning is via git: every spec carries v0.1 (draft) in the header and is bumped on minor/major depending on breaking changes.

Compliance + privacy (quick view)

Guarantee	Specification	What it means
FDA non-device CDS	`CHARTER.md §15`	CHARTER §15 records project design constraints; it does not establish regulatory classification or clinical validation.
No patient data	`CHARTER.md §9.3`	`patient_plans/` and any patient HTML are gitignored. All examples are synthetic.
Solo maintainer delivery	`CHARTER.md §6.1`	The maintainer verifies sources and tests; external clinical review is optional.
No LLM clinical judgment	`CHARTER.md §8.3`	LLMs do not pick regimens, do not generate doses, and do not interpret biomarkers for therapy selection.
No treatment without histology	`CHARTER.md §15.2 C7`	The engine refuses to generate a treatment Plan without `disease.id` or `icd_o_3_morphology` — only a DiagnosticPlan.
Anti automation-bias	`CHARTER.md §15.2 C6`	≥2 alternative tracks are always shown side-by-side; the alternative is never hidden.
Source hosting default = referenced	`SOURCE_INGESTION_SPEC.md §1.4`	We do not duplicate external databases; hosting requires explicit H1-H5 justification.
Free public resource → non-commercial	`CHARTER.md §2`	Many licences (ESMO CC-BY-NC-ND, OncoKB academic, ATC) depend on this. A paid tier would trigger a license audit.
IP-based language auto-select	`client-side, opt-out`	To show the interface in your language, your browser looks up your country from your IP via a third-party service (GeoJS, with ipapi.co as fallback). Only your IP is sent, with no referrer. These direct geo requests do not use the OpenOnco API; the providers determine their own logging and retention policies. The detected country and your manual language choice are stored only in your browser (localStorage) and the manual switch always overrides the IP guess. Ukrainian is shown only for Ukrainian IP addresses; English everywhere else. By using the site you consent to this country lookup — to avoid it, pick a language manually and your choice is remembered.