# chrisguzman77/irin architecture

> Architecture diagram of the GitHub repository chrisguzman77/irin, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/chrisguzman77/irin
- Repository: https://github.com/chrisguzman77/irin

## Overview

Irin is a bedside diabetes-safety system: it reads live or replayed CGM data, forecasts lows, escalates alarms through room outputs and human support, and gives patients, clinicians, and family separate views. The README also documents clinical cards, buddy matching, family stories, dashboards, and retrospective ML. Edges reflect documented product flows; sampled excerpts are partial, so uncertain internal wiring is omitted.

Main entry points: [`backend/app/main.py`](https://github.com/chrisguzman77/irin/blob/dev/backend/app/main.py) (Device API), [`relay/main.py`](https://github.com/chrisguzman77/irin/blob/dev/relay/main.py) (Blind relay), [`backend/app/rounds/relay_client.py`](https://github.com/chrisguzman77/irin/blob/dev/backend/app/rounds/relay_client.py) (Relay client), [`frontend/app/src/App.tsx`](https://github.com/chrisguzman77/irin/blob/dev/frontend/app/src/App.tsx) (Phone app)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_bedside["Bedside safety"]
  node_phone["Phone app<br/>[App.tsx]"]
  node_device_api["Device API<br/>[main.py]"]
  node_cgm["CGM source<br/>[nightscout.py]"]
  node_forecast["Low forecast<br/>[forecast.py]"]
  node_alarm["Alarm ladder<br/>[alarm.py]"]
  node_hardware["Room outputs<br/>[hal.py]"]
  node_presence["Presence radar<br/>[presence.py]"]
  node_night_report["Night report<br/>[reports.py]"]
end

subgraph group_rounds["Clinical rounds"]
  node_rounds_engine["Rounds engine<br/>[evaluate.py]"]
  node_rounds_cards["Cards and steps<br/>[standing.py]"]
  node_rounds_noise["Noise budget<br/>[noise.py]"]
  node_rounds_crypto["Card encryption<br/>[crypto.py]"]
  node_relay_client["Relay client<br/>[relay_client.py]"]
  node_relay["Blind relay<br/>[main.py]"]
  node_doctor["Doctor inbox<br/>[session.js]"]
end

subgraph group_care["Buddy and family"]
  node_buddy["Buddy matching<br/>[directory.py]"]
  node_buddy_hub["Volunteer hub<br/>[hub.py]"]
  node_family_story["Family story<br/>[family_story.py]"]
  node_family_page["Family page<br/>[family.js]"]
end

subgraph group_platform["Data and ML"]
  node_forwarder["Device forwarder<br/>[forward.py]"]
  node_cloud_api["Cloud API<br/>[main.py]"]
  node_cloud_store[("Cloud data store<br/>[ingest.py]")]
  node_dashboards["Dashboards<br/>[dash.py]"]
  node_ml_model["Forecast model<br/>[predict.py]"]
  node_replay["Replay source<br/>[replay.py]"]
end

node_sleeper(("Sleeper"))

node_sleeper -->|"views and acknowledges"| node_phone
node_phone -->|"requests device data"| node_device_api
node_cgm -->|"supplies readings"| node_device_api
node_replay -.->|"supplies demo readings"| node_device_api
node_device_api -->|"requests prediction"| node_forecast
node_ml_model -->|"provides model"| node_forecast
node_device_api -->|"evaluates alarm state"| node_alarm
node_device_api -->|"updates presence"| node_presence
node_alarm -->|"dispatches tones and lights"| node_hardware
node_presence -->|"gates room outputs"| node_hardware
node_device_api -->|"builds morning report"| node_night_report
node_rounds_engine -->|"evaluates night records"| node_rounds_cards
node_rounds_cards -->|"applies send limits"| node_rounds_noise
node_rounds_noise -->|"passes eligible cards"| node_rounds_crypto
node_rounds_crypto -->|"seals cards"| node_relay_client
node_relay_client -->|"sends ciphertext"| node_relay
node_relay -->|"delivers inbox cards"| node_doctor
node_doctor -->|"sends doctor reply"| node_relay
node_relay -->|"polls messages"| node_relay_client
node_device_api -->|"uses matching service"| node_buddy
node_device_api -->|"posts hub updates"| node_buddy_hub
node_buddy -->|"serves buddy directory"| node_relay
node_buddy_hub -->|"serves volunteer hub"| node_relay
node_device_api -->|"creates night story"| node_family_story
node_family_story -->|"shares approved story"| node_family_page
node_device_api -->|"provides device records"| node_forwarder
node_forwarder -->|"posts data batches"| node_cloud_api
node_cloud_api -->|"upserts records"| node_cloud_store
node_dashboards -->|"queries records"| node_cloud_store

click node_phone "https://github.com/chrisguzman77/irin/blob/dev/frontend/app/src/App.tsx"
click node_device_api "https://github.com/chrisguzman77/irin/blob/dev/backend/app/main.py"
click node_cgm "https://github.com/chrisguzman77/irin/blob/dev/backend/app/datasource/nightscout.py"
click node_forecast "https://github.com/chrisguzman77/irin/blob/dev/backend/app/forecast.py"
click node_alarm "https://github.com/chrisguzman77/irin/blob/dev/backend/app/alarm.py"
click node_hardware "https://github.com/chrisguzman77/irin/blob/dev/hardware/hal.py"
click node_presence "https://github.com/chrisguzman77/irin/blob/dev/backend/app/presence.py"
click node_night_report "https://github.com/chrisguzman77/irin/blob/dev/backend/app/reports.py"
click node_rounds_engine "https://github.com/chrisguzman77/irin/blob/dev/backend/app/rounds/evaluate.py"
click node_rounds_cards "https://github.com/chrisguzman77/irin/blob/dev/backend/app/rounds/standing.py"
click node_rounds_noise "https://github.com/chrisguzman77/irin/blob/dev/backend/app/rounds/noise.py"
click node_rounds_crypto "https://github.com/chrisguzman77/irin/blob/dev/backend/app/rounds/crypto.py"
click node_relay_client "https://github.com/chrisguzman77/irin/blob/dev/backend/app/rounds/relay_client.py"
click node_relay "https://github.com/chrisguzman77/irin/blob/dev/relay/main.py"
click node_doctor "https://github.com/chrisguzman77/irin/blob/dev/frontend/clinician/session.js"
click node_buddy "https://github.com/chrisguzman77/irin/blob/dev/relay/directory.py"
click node_buddy_hub "https://github.com/chrisguzman77/irin/blob/dev/relay/hub.py"
click node_family_story "https://github.com/chrisguzman77/irin/blob/dev/backend/app/family_story.py"
click node_family_page "https://github.com/chrisguzman77/irin/blob/dev/frontend/family/family.js"
click node_forwarder "https://github.com/chrisguzman77/irin/blob/dev/backend/app/forward.py"
click node_cloud_api "https://github.com/chrisguzman77/irin/blob/dev/cloud/main.py"
click node_cloud_store "https://github.com/chrisguzman77/irin/blob/dev/cloud/ingest.py"
click node_dashboards "https://github.com/chrisguzman77/irin/blob/dev/cloud/dash.py"
click node_ml_model "https://github.com/chrisguzman77/irin/blob/dev/ml/models/predict.py"
click node_replay "https://github.com/chrisguzman77/irin/blob/dev/backend/app/datasource/replay.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_phone,node_device_api,node_cgm,node_forecast,node_alarm,node_hardware,node_presence,node_night_report toneBlue
class node_rounds_engine,node_rounds_cards,node_rounds_noise,node_rounds_crypto,node_relay_client,node_relay,node_doctor toneAmber
class node_buddy,node_buddy_hub,node_family_story,node_family_page toneMint
class node_forwarder,node_cloud_api,node_cloud_store,node_dashboards,node_ml_model,node_replay toneRose
class node_sleeper toneIndigo
```

## Components

### Bedside safety

- [Phone app](https://github.com/chrisguzman77/irin/blob/dev/frontend/app/src/App.tsx): `frontend/app/src/App.tsx`
- [Device API](https://github.com/chrisguzman77/irin/blob/dev/backend/app/main.py): `backend/app/main.py`
- [CGM source](https://github.com/chrisguzman77/irin/blob/dev/backend/app/datasource/nightscout.py): `backend/app/datasource/nightscout.py`
- [Low forecast](https://github.com/chrisguzman77/irin/blob/dev/backend/app/forecast.py): `backend/app/forecast.py`
- [Alarm ladder](https://github.com/chrisguzman77/irin/blob/dev/backend/app/alarm.py): `backend/app/alarm.py`
- [Room outputs](https://github.com/chrisguzman77/irin/blob/dev/hardware/hal.py): `hardware/hal.py`
- [Presence radar](https://github.com/chrisguzman77/irin/blob/dev/backend/app/presence.py): `backend/app/presence.py`
- [Night report](https://github.com/chrisguzman77/irin/blob/dev/backend/app/reports.py): `backend/app/reports.py`

### Clinical rounds

- [Rounds engine](https://github.com/chrisguzman77/irin/blob/dev/backend/app/rounds/evaluate.py): `backend/app/rounds/evaluate.py`
- [Cards and steps](https://github.com/chrisguzman77/irin/blob/dev/backend/app/rounds/standing.py): `backend/app/rounds/standing.py`
- [Noise budget](https://github.com/chrisguzman77/irin/blob/dev/backend/app/rounds/noise.py): `backend/app/rounds/noise.py`
- [Card encryption](https://github.com/chrisguzman77/irin/blob/dev/backend/app/rounds/crypto.py): `backend/app/rounds/crypto.py`
- [Relay client](https://github.com/chrisguzman77/irin/blob/dev/backend/app/rounds/relay_client.py): `backend/app/rounds/relay_client.py`
- [Blind relay](https://github.com/chrisguzman77/irin/blob/dev/relay/main.py): `relay/main.py`
- [Doctor inbox](https://github.com/chrisguzman77/irin/blob/dev/frontend/clinician/session.js): `frontend/clinician/session.js`

### Buddy and family

- [Buddy matching](https://github.com/chrisguzman77/irin/blob/dev/relay/directory.py): `relay/directory.py`
- [Volunteer hub](https://github.com/chrisguzman77/irin/blob/dev/relay/hub.py): `relay/hub.py`
- [Family story](https://github.com/chrisguzman77/irin/blob/dev/backend/app/family_story.py): `backend/app/family_story.py`
- [Family page](https://github.com/chrisguzman77/irin/blob/dev/frontend/family/family.js): `frontend/family/family.js`

### Data and ML

- [Device forwarder](https://github.com/chrisguzman77/irin/blob/dev/backend/app/forward.py): `backend/app/forward.py`
- [Cloud API](https://github.com/chrisguzman77/irin/blob/dev/cloud/main.py): `cloud/main.py`
- [Cloud data store](https://github.com/chrisguzman77/irin/blob/dev/cloud/ingest.py): `cloud/ingest.py`
- [Dashboards](https://github.com/chrisguzman77/irin/blob/dev/cloud/dash.py): `cloud/dash.py`
- [Forecast model](https://github.com/chrisguzman77/irin/blob/dev/ml/models/predict.py): `ml/models/predict.py`
- [Replay source](https://github.com/chrisguzman77/irin/blob/dev/backend/app/datasource/replay.py): `backend/app/datasource/replay.py`

### Other components

- **Sleeper**

## Connections

- Sleeper → Phone app: views and acknowledges
- Phone app → Device API: requests device data
- CGM source → Device API: supplies readings
- Replay source → Device API: supplies demo readings
- Device API → Low forecast: requests prediction
- Forecast model → Low forecast: provides model
- Device API → Alarm ladder: evaluates alarm state
- Device API → Presence radar: updates presence
- Alarm ladder → Room outputs: dispatches tones and lights
- Presence radar → Room outputs: gates room outputs
- Device API → Night report: builds morning report
- Rounds engine → Cards and steps: evaluates night records
- Cards and steps → Noise budget: applies send limits
- Noise budget → Card encryption: passes eligible cards
- Card encryption → Relay client: seals cards
- Relay client → Blind relay: sends ciphertext
- Blind relay → Doctor inbox: delivers inbox cards
- Doctor inbox → Blind relay: sends doctor reply
- Blind relay → Relay client: polls messages
- Device API → Buddy matching: uses matching service
- Device API → Volunteer hub: posts hub updates
- Buddy matching → Blind relay: serves buddy directory
- Volunteer hub → Blind relay: serves volunteer hub
- Device API → Family story: creates night story
- Family story → Family page: shares approved story
- Device API → Device forwarder: provides device records
- Device forwarder → Cloud API: posts data batches
- Cloud API → Cloud data store: upserts records
- Dashboards → Cloud data store: queries records