HelixTrace

HelixTrace is a governed forensic-DNA investigation workspace . It organizes authorized evidence, profiles, quality controls, candidate comparisons, provenance graphs, and review-controlled reports. Deterministic services and qualified people make forensic decisions; configurable LLM agents can only draft, explain, check, and document.

Implemented MVP

Pillar	Implemented capability
Data	Dataset cards, lawful-basis fields, STR profile normalization, manual entry, CSV/XLSX allele-table import, source-file SHA-256 preservation, local object storage, and chain-of-custody events.
Case workspace	Case, evidence, sample, and laboratory-batch records with legal-basis and retention fields; profiles can be attached to those provenance records through the API.
QC	Visible deterministic flags for partial profiles, low-template signals, mixture triage, supplied degradation/control/artifact/replicate context, secondary-transfer caution, and elimination-reference screening. QC failures cannot be cleared by an assistant.
Search	Exact, controlled partial, one-mismatch, and elimination-scope candidate comparison with reproducible parameters, candidate-detail output, independent technical review, and audit events.
Population data	Versioned frequency-table imports with source/license/population metadata; a configuration-gated, deterministic research RMP check with retained assumptions and input coverage.
Graph & leads	Local explainable case/evidence/profile graphs, deterministic allele-token similarity triage, optional Neo4j synchronization, and externally generated kinship/origin/lineage lead records with independent review.
Reports	Candidate-match, exclusion, case-linkage, kinship/origin-lead and audit-packet drafts; independent technical review, optional legal/policy review, final immutable SHA-256 hash, and logged JSON export.
Assistants	Optional OpenAI-compatible dataset-curator, ingestion-mapping, QC, search-planning, graph, kinship/origin, report, audit, and SOP/standards draft endpoints. Agents receive a constrained assembled context, have no direct database access, never write evidence, and every draft is logged.
Sequence library	Attested synthetic-only nucleotide CSV import with source-file SHA-256 preservation, recomputed base composition, paginated browsing, and a base-composition viewer. Source-supplied metrics are retained as untrusted annotations and flagged when they disagree with the recomputation.
Visual research	Live RCSB PDB 1BNA 3D DNA view, sequence-derived B-DNA geometry for a selected synthetic record, and a Neo4j view of source-declared IGSR public-research pedigree records.
Comparison and graph visuals	A locus-by-locus electropherogram-style ladder over the 18 core loci, a concordance dial, a 3D helix whose rungs are coloured by per-locus comparison state, a draggable force-directed case graph with scored triage links drawn as weighted dashed edges, and two declared-pedigree views (hop orbit and a conventional pedigree chart). Every mark is drawn from a deterministic backend response.

The UI never substitutes fabricated evidence for a failed source or an empty workspace, and no profile, frequency, or case data is seeded automatically.

Outside production, the profile form offers an explicit Synthetic donor generator for demonstration and manual testing. It fills computer-generated allele calls across the 18 core loci, records synthetic_demo: true and the donor name in the profile's source metadata, and is hidden whenever HELIXTRACE_ENV=production. Reusing the same donor name reproduces the same genotype, which is how you create a scene sample and a reference sample that compare as a match. It is deterministic local code, not a model: the guardrail against LLM-based allele calling is unchanged.

Workspace layout

The sidebar follows the investigation in order. Each step is one screen; screens with more than one job use tabs rather than separate sidebar entries.

Step	Screen	Contains
1	Scene intake	Case, agency assignment, retention and legal hold, evidence items, samples, chain of custody
2	Profile & match	Record or import an STR profile, run a policy-controlled candidate comparison against the locus ladder, concordance dial and 3D helix, triage QC flags
3	Relationship graph	Force-directed case/evidence/profile graph with Neo4j sync and similarity triage, plus declared IGSR research relatives as a hop orbit or pedigree chart
4	3D DNA view	Live RCSB PDB structure and sequence-derived geometry, plus the synthetic sequence library
5	Case file	Report drafting through its review gates and export, plus external investigative lead records

Governance, data-source registration, validated-engine exchange, the workspace metrics overview, and the audit chain sit under Advanced in the sidebar. They are part of the control framework rather than the per-case path, so they stay collapsed until needed.

Reading the comparison and relationship visuals

Every visual is a rendering of a stored record, never a new inference. On Profile & match, running a comparison draws the selected candidate as a ladder of the 18 core loci: the query's stored calls rise above each baseline, the candidate's mirror below, and peak height is the recorded RFU scaled against the tallest peak in that pair. Cells are coloured by the backend's own comparison state — concordant, discordant, or not compared — and selecting a cell isolates that locus in the 3D helix beside it. The helix is a schematic; its rungs stand for loci, not for the sequenced molecule. Full concordance across every locus is still a candidate comparison, not an identification.

On Relationship graph, the case graph is a force layout of the same nodes and edges the API returns, and any node can be dragged. Scored triage links are drawn as dashed edges whose width tracks the score. The declared-relatives tab offers a hop orbit, which places each relative on the ring matching its declared pedigree hop count, and a pedigree chart using conventional symbols (square for declared male, circle for declared female, diamond where sex is not declared) with parents joined by a mating line. Both read only from the source-declared IGSR pedigree: hop counts are file-declared distances, not DNA similarity scores or relationship probabilities.

Non-claims and hard boundaries

This is not an accredited forensic laboratory system, a CODIS/NDIS integration, or an identity-search system. It must not be used to identify a criminal, identify a relative from a DNA profile, search a consumer/public genealogy database, issue a match/no-match conclusion, make activity-level conclusions, or interpret a complex mixture. Kinship, origin, Y-lineage, and mtDNA records are imported only from approved external workflows and remain review-required investigative leads.

The RMP route is a deterministic research implementation, disabled by default, and explicitly labels its assumptions. Enable it only after the laboratory’s separate validation, population-genetics review, and governance approval. The optional LLM route never performs allele calling, statistics, QC clearing, report approval, or autonomous reporting.

AutoDock Vina is not used for the DNA structure view: it is a ligand-docking/scoring program, not a forensic DNA comparison or molecular-structure viewer. The DNA workspace renders live RCSB PDB coordinates with 3Dmol.

Configuration

Copy .env.example to .env; keep .env local and never commit secrets. Every runtime setting is environment-driven.

Setting	Default	Purpose
HELIXTRACE_HOST	127.0.0.1	API bind host
HELIXTRACE_PORT or PORT	8000	API port
HELIXTRACE_DB	data/helixtrace.sqlite3	SQLite development database
HELIXTRACE_OBJECT_DIR	data/objects	Local source-file store
HELIXTRACE_MAX_UPLOAD_BYTES	26214400	Upload limit
HELIXTRACE_CORS_ORIGINS	Vite localhost origins	Comma-separated allowed browser origins
HELIXTRACE_AUTH_MODE	local-dev	Local role header mode, or token for opaque local API-token bindings
HELIXTRACE_ENABLE_RESEARCH_STATISTICS	false	Enables the research-only RMP endpoint
HELIXTRACE_REQUIRE_MANUAL_DOUBLE_ENTRY	true	Requires independent re-entry of manual allele calls
HELIXTRACE_SEQUENCE_MAX_RECORDS	50000	Row ceiling for a synthetic sequence CSV import
HELIXTRACE_SEQUENCE_MAX_LENGTH	10000	Base ceiling for a single synthetic sequence
HELIXTRACE_REPORT_REQUIRE_LEGAL_REVIEW	false	Requires separate legal/policy review before finalization
HELIXTRACE_ENABLE_ASSISTANTS	false	Enables controlled assistant drafts only when provider/model/base URL/key are all configured
HELIXTRACE_LLM_ALLOW_EVIDENCE_CONTEXT	false	Allows the limited assembled context to include approved source metadata; allele calls are never sent by this code path
VITE_PORT	5173	Vite development server port
VITE_API_TARGET	http://127.0.0.1:8000	Vite API proxy target

The browser receives only safe configuration status—never an API key, token, database credential, or raw environment variable value.

Run locally

From the workspace root (HelixTrace), one-time setup (skip any step already done manually):

cd .\HelixTrace
if (!(Test-Path .env)) { Copy-Item .env.example .env }
if (!(Test-Path .venv)) { python -m venv .venv }
.\.venv\Scripts\Activate.ps1
pip install -r requirements.txt
python -m backend

In another terminal:

cd .\HelixTrace_UI
if (!(Test-Path .env)) { Copy-Item .env.example .env }
pnpm install --frozen-lockfile
pnpm dev

If the virtualenv, Python packages, or UI node_modules are already installed, activate (or reuse) them and start the servers directly:

# API
cd .\HelixTrace
.\.venv\Scripts\Activate.ps1
python -m backend

# UI (separate terminal)
cd .\HelixTrace_UI
pnpm dev

Open the Vite URL shown in the terminal. The local role selector exists only for HELIXTRACE_AUTH_MODE=local-dev; token mode reads HELIXTRACE_API_TOKENS_JSON from the API environment. Production use requires a real identity provider, MFA, server-side roles, encryption, retention/expungement controls, and independent audit governance.

Run with Docker and Neo4j

From the shared workspace directory:

docker compose -f .\HelixTrace\docker-compose.yml up --build

The public app port follows HELIXTRACE_PORT (default 8000). Neo4j Browser is exposed on port 7474. The compose credentials are local-development-only and must be replaced before any shared environment.

Validate

cd .\HelixTrace
.\.venv\Scripts\python.exe -m unittest discover -s tests -v

cd ..\HelixTrace_UI
node .\node_modules\vite\bin\vite.js build --configLoader native

The test suite uses isolated fixtures only to validate deterministic code. It does not populate the application database or appear in the UI.