medicallib_rust/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Build, Test, and Development Commands

Core workflows

• Build library: cargo build (debug) or cargo build --release (optimized)
• Build FFI shared library: cargo build --release --features ffi (generates C header via cbindgen)
• Run tests: cargo test (all tests) or cargo test --test <name> (single integration test file)
• Run examples: cargo run --example usage, cargo run --example patient, cargo run --example tracing_demo
• Run demo monitor: cargo run --example demo_app --features demo-monitor
• Benchmarks: cargo bench (runs Criterion benchmarks; results in target/criterion/)
• Format code: cargo fmt --all (run before committing)
• Lint: cargo clippy --all-targets -- -D warnings (enforce before committing)

Packaging binary distributions

• Linux/macOS: Run ../scripts/package.sh [target-triple] from medicallib_rust/
• Windows: Run ..\scripts\package.ps1 [target-triple] from medicallib_rust\
• Artifacts placed in medicallib_rust/dist/ as both .tar.gz and .zip

Architecture Overview

Core structure

• src/lib.rs: Crate facade re-exporting public API (Patient, Organ, types, errors)
• src/types.rs: Domain types (Blood, BloodPressure, OrganType, VitalSign)
• src/error.rs: MedicalError enum using thiserror
• src/patient.rs: Patient struct orchestrating Vec<Box<dyn Organ>> with inter-organ signal routing
• src/organs/mod.rs: Organ trait and OrganInfo; per-organ modules (heart, lungs, brain, etc.)
• src/ekg/mod.rs: EKG monitoring system with configurable leads
• src/ffi.rs: C-compatible FFI layer (feature ffi); header auto-generated to ffi/medicallib.h by build.rs using cbindgen

Organ system

• Each organ module implements the Organ trait (id(), organ_type(), update(dt), summary(), as_any(), as_any_mut())
• Patient owns organs as trait objects, calls update() each tick, and routes signals between organs
• Inter-organ communication examples:
  • Lungs SpO2 → Heart rate adjustment
  • Kidneys GFR → Bladder volume accumulation
  • Brain autonomic signals → Heart rate variability and respiratory drive
  • Bloodstream perfusion → multiple organ metabolic states

FFI boundary

• Opaque handle: MLPatient pointer to boxed Patient
• Functions: ml_patient_new/free/update, ml_patient_summary, ml_patient_organ_summary, medicallib_bmi
• Memory: All returned strings allocated by Rust must be freed via ml_string_free
• Build script: build.rs runs cbindgen when --features ffi is enabled, updates ffi/medicallib.h if changed
• Validation: Any change to src/ffi.rs must be tested against examples/c/ffi_example.c

Testing and benchmarks

• Integration tests: tests/ directory (e.g., tests/patient.rs, tests/ffi.rs)
• Benchmarks: benches/heart.rs uses Criterion; compare results across runs for performance regressions
• Unit tests: In-module #[cfg(test)] blocks for focused invariants

Important Development Notes

When modifying FFI

1. Edit src/ffi.rs
2. Run cargo build --features ffi to regenerate ffi/medicallib.h via cbindgen
3. Verify C example still compiles: gcc -o ffi_example examples/c/ffi_example.c -L target/release -lmedicallib_rust
4. Update cbindgen.toml only if header generation settings need adjustment

Adding new organs

1. Create module in src/organs/<organ_name>.rs
2. Define struct implementing Organ trait
3. Add module declaration and public re-export in src/organs/mod.rs
4. Update Patient signal structs and couple_organs() method if inter-organ communication needed
5. Add corresponding OrganType variant in src/types.rs
6. Update FFI constants in src/ffi.rs if organ needs FFI exposure

Cargo features

• serde: Enables serialization on public types
• ffi: Exposes C ABI; triggers cbindgen in build.rs
• demo-monitor: Required for demo_app example with colorized dashboard

CI workflows

• GitHub Actions: .github/workflows/ci.yml
• Gitea Actions: .gitea/workflows/ci.yml
• Both run tests, clippy, formatting checks, and cross-platform builds

Key Patterns

Patient simulation loop

let mut patient = Patient::new("case-01")?.initialize_default();
loop {
    patient.update(dt_seconds);
    let summary = patient.patient_summary();
    // Process vitals...
}

Accessing specific organ

let heart = patient.find_organ_typed::<Heart>()?;
println!("HR: {}", heart.heart_rate_bpm());

Inter-organ signals

Patient's couple_organs() method reads state from one organ (e.g., Lungs::spo2_pct()) and injects it into another (e.g., Heart::receive_spo2_signal()). Add new signal fields to the internal *Signals structs in patient.rs when coupling new organ interactions.