# Heurion Technical Specification and Architecture Manual (llms-full.txt)

## Architecture Overview

Heurion is structured as a modular medical AI and clinical research operating system composed of:
1. `@heurion2/platform`: TypeScript/Node/Hono platform server orchestrating real-time Yjs CRDT documents, SQLite/WAL storage, user sessions, study management, and MCP bridges.
2. `@heurion2/canvas-service`: Standalone OmniCanvas / AgentDoc canvas service with pure generic document manipulation and MCP server tools.
3. `apps/imaging-worker`: High-performance Python/FastAPI medical computing microservice running MONAI, PyTorch, Nibabel, and Pydicom.
4. `apps/embedder`: Local embedding service using GTE-multilingual for vector retrieval and memory deduplication.
5. Web Client (`apps/platform/web`): Vanilla TypeScript client featuring real-time collaborative Prosemirror rich-text editing, SVG mechanism chart design, 2D/3D MPR medical viewer with NiiVue WebGL2 integration.

## Clinical Imaging Capabilities (apps/imaging-worker)

The imaging microservice (`127.0.0.1:8004`) exposes standardized REST and MCP endpoints for volumetric radiology and oncology quantification:

### Supported Physical and Deep-Learning Models
Capabilities verified by running on public dataset samples (see `scripts/generate_all_case_study_images.py`):
1. `spleen_segmenter`: MONAI spleen_ct 3D-UNet with official Model Zoo weights. Generates a binary mask, 3D volume, and RECIST longest diameter.
2. RECIST 1.1 measurement (`recist.calculate_recist_metrics`): longest diameter on the max-area slice, perpendicular extent, and 3D volume computed from a segmentation mask.
3. Radiomics (`radiomics.extract_radiomics_features`): 46 features (3D shape, first-order, GLCM, GLRLM); not yet validated against IBSI reference values.
4. Multi-planar reconstruction in canonical LPS orientation.

Not presented as validated capabilities: whole-body body composition (current implementation is HU thresholding with a heuristic L3 slice, not the TotalSegmentator model; SMI requires patient height), prostate MRI zonal segmentation (empty output on the bundled sample), coronary calcium scoring, heuristic bronchiectasis/mucus quantification (unvalidated threshold method), and emphysema LAA% (lung mask is not anatomically constrained).

### REST Endpoints
- `GET /health`: Health status and GPU/Metal device telemetry.
- `GET /models`: Registry of installed models, supported modalities, and readiness flags.
- `GET /samples`: List of clinical reference samples (DICOM/NIfTI).
- `POST /segment`: End-to-end 3D volumetric inference.
- `POST /mpr/slice`: 2D multi-planar reconstruction (Axial, Coronal, Sagittal) with windowing presets (`lung`, `mediastinum`, `abdomen`, `bone`, `brain`).
- `POST /mpr/diff-slice`: Voxel difference between two co-registered volumes (requires two scans of the same subject).
- `POST /interactive/segment`: VISTA-3D positive and negative click-prompt interactive lesion sculpting.

## Biostatistics and Sandbox Execution

Heurion executes statistical calculations within a strictly partitioned Unix execution environment:
- Environment Isolation: Processes run under an isolated unprivileged operating system user account (`sandboxUid`); outbound network is restricted by iptables to the platform's own port.
- Execution Language: Sandboxed Python 3 with pandas, scipy, statsmodels, lifelines, pyreadstat, openpyxl, and matplotlib. R is not installed.
- Data Protection: The sandbox has no direct access to the platform database, platform secrets, or other users' workspaces; it receives only short-lived access tokens.
- Table 1 Export: Native Word (.docx) generation producing true academic three-line tables with standard font sizing (Songti / Times New Roman), 1.5pt outer rules, 0.5pt inner rules, and explicit statistical test annotations (Chi-square, Fisher's exact, Student's t-test, Mann-Whitney U).
- Flowcharts: Standardized CONSORT 2010 and STROBE participant flow diagram generator tracing enrolled, excluded (with explicit exclusion rationales), randomized, allocated, lost to follow-up, and analyzed counts.

## Literature Citation Verification and Anti-Hallucination

Literature citations are checked against bibliographic databases:
- Primary Source: NCBI PubMed E-Utilities REST API.
- Secondary Sources: Europe PMC, Crossref REST API, and OpenAlex scholarly index.
- Verification Logic:
  1. Extraction of DOI, PMID, journal name, publication year, author list, and clinical findings.
  2. Direct query against NCBI PubMed to fetch the authoritative XML record.
  3. Strict matching of reported statistical estimates (Hazard Ratios, Odds Ratios, Confidence Intervals, p-values).
  4. Marking citations as `supported`, `unsupported`, `unclear`, or `missing_citation` with inline rationale badges.

## Model Context Protocol (MCP) Integration

Heurion exposes compliant Anthropic Model Context Protocol (MCP) servers allowing autonomous agents (such as Claude Desktop, Cursor, and Cline) to directly orchestrate clinical workflows:
- Protocol Version: 2024-11-05 (stdio & SSE transport).
- Endpoint: `/mcp` on platform server and standalone canvas MCP at `canvas-service/src/mcp-server.ts`.
- Available Tools:
  - `imaging_models`: Query registered MONAI and PyTorch models and device health.
  - `imaging_analyze`: Run volumetric inference on NIfTI/DICOM series and return quantitative biomarkers.
  - `imaging_slice`: Extract 2D orthogonal MPR key slices (Axial/Coronal/Sagittal) with HU windowing.
  - `imaging_radiomics`: Compute 3D shape, first-order, and texture features.
  - `search_literature`: Federated query over PubMed, Europe PMC, and OpenAlex.
  - `verify_citation`: Validate extracted clinical claims against authentic PubMed XML.
  - `canvas_create_doc` / `canvas_batch_ops`: Programmatically compose and edit structured research manuscripts.

## Security, Tenancy, and Compliance

- Multitenancy: Strict hospital organization (`org`) and personal space (`personal`) isolation. Users belonging to Hospital A cannot access studies, patients, documents, or memory signals of Hospital B.
- PHI Redaction: Rule-based scanning that detects Chinese Resident Identity Cards (18 digits, checksum validated), bank card numbers, phone numbers, medical record numbers, and names adjacent to diagnoses.
- Cryptographic Sharing: Time-limited, scope-restricted cryptographic claim codes (`PhrClaim`) for secure patient-to-hospital data transmission without persistent shared credentials.
- External LLM: AI conversations are sent to an external LLM provider through the platform proxy; submit only de-identified data.
- Official Support & Feedback: support@heurion.org