Skip to content

Software Design Description (SDD)

Status: Draft v0.1
Owner: BionicLoop engineering

1. Design Intent

This design implements a CGM-triggered closed-loop runtime with:

  • deterministic cadence state
  • degraded execution behavior when inputs are unavailable
  • explicit gating for pump command application
  • traceable per-step telemetry

2. Major Components

  • SDD-APP-001: LoopRuntimeEngine (BionicLoop/Runtime/LoopRuntimeEngine.swift) handles wake handling, availability logic, session control, and telemetry orchestration.
  • SDD-CORE-001: LoopRuntimeCoordinator (BionicLoopCore/.../Runtime/LoopRuntimeCoordinator.swift) handles due-step logic, input assembly, algorithm invocation, and command application.
  • SDD-ALG-001: RealBUDosingAlgorithm + Algo2015Bridge map runtime input into C bridge structs and receive output/state.
  • SDD-PUMP-001: PumpServiceAdapter + PumpStatusObserver handle status refresh, command execution, delivery reconciliation, home-status projection, and auto-polling while deliveryState == delivering.
  • SDD-CGM-001: G7ViewModel + CGM subsystem adapters provide CGM state ingestion and wake trigger source.
  • SDD-LOG-001: LoopTelemetryStore stores per-step records for UI + export.
  • SDD-ALERT-001 (planned): Alert normalization/presentation layer normalizes alerts from pump, CGM, algorithm/runtime, and app safety policy into a common model with severity, dedupe/debounce, precedence, and acknowledgment behavior.

3. Runtime Sequence (Nominal)

  1. New CGM timestamp arrives.
  2. LoopRuntimeEngine triggers coordinator doWork.
  3. Coordinator computes expected step from anchor + interval.
  4. Coordinator builds algorithm input:
  5. CGM (or unavailable -1 by policy).
  6. Pump fields (or unavailable values if pump not available).
  7. Algorithm returns recommendation and updated internal state blob.
  8. If pump status is available and recommendation passes gates, command is attempted.
  9. Telemetry record is persisted with input/output/command fields.
  10. Pump status refresh reconciles delivered/requested units.

4. Key Design Policies

  • SDD-POL-001 (Cadence): anchored 5-minute slot model.
  • SDD-POL-002 (CGM): step 0 strict gate, step >0 degraded allowed.
  • SDD-POL-003 (Pump): unavailable pump permits algorithm step but blocks command application.
  • SDD-POL-004 (Meal announce): explicit pump-ready gating (known and not delivering), established first-step cadence anchor requirement, borrow-window gating for pre-due execution, and current-due-step execution when request arrives after slot is due/missed. This policy is marked provisional pending team/clinical review.
  • SDD-POL-005 (Reset): full session reset clears persisted runtime + algorithm + timeline session data.
  • SDD-POL-006 (Home status): state precedence is deterministic and runtime-derived.
  • SDD-POL-007 (Modal setup cancellation): startup/setup modals for CGM and Pod provide direct dismiss behavior via explicit Cancel, including persisted-manager/no-active-pod Pod setup.
  • SDD-POL-009 (Meal composer lifecycle safety): if app scene transitions to background while meal composer is presented, the composer is auto-cancelled/dismissed.
  • SDD-POL-008 (Alert policy, planned): normalize multi-source alerts to one model, enforce severity precedence and prevent critical-alert masking, debounce transient reconnect churn while retaining true-fault alerts, and define per-alert clear/acknowledge behavior.

5. Data Persistence

  • SDD-DATA-001: runtime cadence state is persisted in UserDefaultsLoopRuntimeStateStore.
  • SDD-DATA-002: algorithm state blob is persisted in UserDefaultsAlgoStateStore.
  • SDD-DATA-003: step telemetry is persisted in LoopTelemetryStore.
  • SDD-DATA-004: device managers are persisted via app delegates for reconnect behavior.

6. Requirement Allocation

SRS ID Design Element(s)
SRS-RUN-001, SRS-RUN-002 SDD-APP-001, SDD-CORE-001, SDD-POL-001
SRS-CGM-001..004 SDD-CORE-001, SDD-POL-002, SDD-CGM-001
SRS-PUMP-001..005 SDD-PUMP-001, SDD-POL-003
SRS-MEAL-001..003 SDD-APP-001, SDD-CORE-001, SDD-POL-004
SRS-STATE-001..003 SDD-DATA-001..004, SDD-POL-005
SRS-LOG-001..003 SDD-LOG-001
SRS-UI-001..004 SDD-APP-001, SDD-POL-006, SDD-POL-007, SDD-POL-009
SRS-VAL-001 Home settings UI + runtime profile normalization
SRS-ALERT-001..006 SDD-ALERT-001, SDD-POL-008
SRS-SEC-001..002 SDD-LOG-001 + Docs/Quality/CybersecurityPlan.md

7. Design Constraints

  • iOS background execution is opportunistic; runtime requires robust skip/degraded behavior.
  • External device SDK behavior (OmniBLE, G7SensorKit) constrains event cadence and status timing.
  • Closed-loop safety policy requires avoiding manual bolus path exposure.