Platform Architecture
One core + scenario packs + credibility services + dual replay frontends
Engineering skeleton of ISSP: what each hybrid-modeling layer owns, how World / ParameterSet / MeasurementModel are audited, how modules ablate, how Web / Unity / Unreal share one replay protocol, plus performance budget and monorepo shape.
§ 1
Unified core: ABM + global ODE/difference + 2D reaction–diffusion
Hybrid modeling: discrete agents, system scalars and spatial fields couple inside one World timestep.
| Layer | Owns | Typical entities |
|---|---|---|
| ABM | Birth/death/division/migration/interactions | Epithelium, mac/DC, NK, CD8 T, B/plasma, neutrophils, bacteria, tumor cells |
| Global ODE/diff | System scalars / simplified PK | Antibody titer, some cytokine totals, drug concentration |
| 2D RD | Tissue-slice fields: diffusion, decay, sources, BCs | IFN, inflammatory and chemokine FieldGrid |
§ 2
World / ParameterSet / MeasurementModel
Split state, parameters and observation mapping for auditability and versioning.
- WORLD
Simulation state
grid W×H; agents; fields; time t/step/dt; rng_state; provenance (param_set_id / model_version / scenario_version / commit_hash).
- PARAMETER SET
Parameters
params; schema (unit, min, max, prior, description, source); provenance (source / calib task / timestamp / hash).
- MEASUREMENT MODEL
Observation map
name/version; g(·); noise & LOD; units/transforms; bind public_data columns.
§ 3
Mechanism module interface
Modules register as switchable units: World slice + parameter subset → events / field sources / scalar updates. Ablation disables or null-ops a module.
- Infection & replication
- Innate alarm (IFN…)
- Innate killing (NK / neutrophils)
- Adaptive effectors (CTL / antibody)
- Suppression & exhaustion
- Drug / intervention script executor
module_manifest.yaml (structure example)
modules:
- id: ifn_alarm
enabled: true
inputs: [infected_cells, field.IFN]
outputs: [field.IFN_source]
ablation_null: zero_source§ 4
Numerical guardrails & determinism
Fixed seed and serializable rng_state; checkpoint/restore; deterministic replay under fixed version and floating-point policy.
Output tiers: signals / observables / endpoints. Verification-lite checks dt and grid sensitivity; default relative endpoint change ≤ 20%.
§ 5
Sustainable evolution
Scenario packs and model versions evolve independently; parameter schemas carry source notes and calibratable flags; deepen mechanisms after a public-data credibility baseline.
AI-ready artifacts (intervention_script / experiment_request, …) land early; capabilities arrive by roadmap phase.
§ 6
Diagnosis & ablation
Explainable diagnosis: rule labels + module ablation + contribution hints. Taxonomy examples: clearance failure, inflammation runaway, immune escape, suppression/exhaustion, tumor progression.
diagnosis_request (structure example)
run_id: "<id>"
ablate: [ifn_alarm]
compare_endpoints: [T_clear, inflammation_AUC]
output: diagnosis_report.json§ 7
Logical components & data flow
§ 8
Unified replay protocol
Parquet shards + JSON index with provenance columns. Reports cite segments via time_range + filters.
replay_ref (structure example)
replay_ref:
run_id: "<id>"
time_range: [t0, t1] # explanatory placeholders, not measured
filters: { cell_types: [CD8], events: [kill] }
index: replay/index.json§ 8.1
API sketch
Interface shapes — not a deployed contract.
Planned orchestration surface: submit runs, read replay, diagnosis, strategy suggest.
API sketch
POST /runs
GET /runs/{id}/replay
POST /runs/{id}/diagnosis
POST /ai/suggest # calibrated + UQ model versions only§ 9
Three frontends & phases
| Frontend | Duty | Phase |
|---|---|---|
| Web | Lightweight replay, report linkage, research demo entry | v1 required (player embed planned here) |
| Unity | High-fidelity exhibit delivery first | Phase 2 |
| Unreal | Higher fidelity / performance path | Phase 3 staged |
§ 10
Stack & monorepo
Planned stack: simulation core (Python/scientific), FastAPI, PostgreSQL / MinIO / Redis, Web player app (separate from this marketing site), Unity / Unreal clients.
Monorepo packages: core / scenarios / credibility / api / web-player / clients. This portal is the standalone Next.js OUTLIVE-Portal repo.
§ 11
Performance budget
| Item | Default acceptance target |
|---|---|
| Grid | ≤ 128×128 |
| Entity cap | default 20k |
| Single-machine CPU | ~1–5 min / run (scenario-dependent) |
| Replay size | ≤ 200MB / run |
Design targets; adjustable in COU / packs — not measured on this site.