Skip to content

Visual Architecture

This page gives code contributors the shortest possible map of how the IINTS-AF SDK fits together before they edit a subsystem.

End-To-End Flow

flowchart LR
    A["Datasets, scenarios, and patient profiles"] --> B["Data layer\nsrc/iints/data"]
    B --> C["Simulation orchestration\nsrc/iints/highlevel.py"]
    C --> D["Algorithm API\nsrc/iints/api"]
    C --> E["Virtual patient + simulator\nsrc/iints/core"]
    D --> F["Candidate insulin decision"]
    E --> F
    F --> G["Deterministic safety supervisor\nsrc/iints/core/safety"]
    G --> H["Run bundle\nCSV + metadata + audit + report"]
    H --> I["Analysis and posters\nsrc/iints/analysis"]
    H --> J["Optional AI explanation\nsrc/iints/ai"]
    H --> K["Validation + replay\nsrc/iints/validation"]

The important design rule is that a candidate algorithm may propose insulin, but the deterministic safety supervisor remains a separate hard gate before outputs are accepted.

Source Layout

flowchart TD
    CLI["cli/\nPublic commands"] --> HIGH["highlevel.py\nWorkflow orchestration"]
    CLI --> LIVE["live_patient/ + jetson/\nEdge runtime"]
    HIGH --> API["api/\nAlgorithm contract"]
    HIGH --> CORE["core/\nSimulator, patient, safety"]
    HIGH --> DATA["data/\nImport, registry, MDMP, realism"]
    HIGH --> ANALYSIS["analysis/\nMetrics, reports, studies"]
    ANALYSIS --> AI["ai/\nLocal explanation layer"]
    CORE --> VALIDATION["validation/\nReplay + safety contracts"]
    LIVE --> CORE
    LIVE --> DATA
    RESEARCH["research/\nPredictor training helpers"] --> CORE

One Simulation Step

sequenceDiagram
    participant Scenario
    participant Patient
    participant Algorithm
    participant Supervisor
    participant Recorder

    Scenario->>Patient: meal / exercise / sensor event
    Patient->>Algorithm: glucose, IOB, carbs, context
    Algorithm->>Supervisor: candidate insulin decision
    Supervisor->>Supervisor: validate bounds, trends, IOB, contract
    Supervisor->>Patient: accepted or overridden dose
    Patient->>Recorder: next simulated state
    Supervisor->>Recorder: intervention reason if any

Edge And Hardware Boundary

flowchart LR
    A["Linux-side SDK runtime\nPi / UNO Q Linux side / Jetson"] --> B["Patient runtime + safety logic"]
    B --> C["HTTP / serial bridge"]
    C --> D["UNO Q microcontroller sketch"]
    B --> E["Snapshots, archives, reports"]

The microcontroller bridge is intentionally thin. The main simulation state, safety policy, replay data, and reporting stay on the Linux-side SDK runtime.

Where To Edit What

If You Need To Change Start In
dose validation, safety limits, override reasons src/iints/core/safety/, src/iints/core/supervisor.py
simulation timing, patient updates, event handling src/iints/core/simulator.py, src/iints/core/patient/
algorithm plugin contract src/iints/api/
command behavior or user-facing flows src/iints/cli/
dataset imports, realism, certification src/iints/data/
reports, posters, study summaries src/iints/analysis/
Pi / UNO Q / Jetson runtime src/iints/live_patient/, src/iints/jetson/
local AI summaries and guardrails src/iints/ai/