# mwdearing/health-relay architecture

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

- Interactive diagram: https://gitdiagram.com/mwdearing/health-relay
- Repository: https://github.com/mwdearing/health-relay

## Overview

HealthRelay moves permitted Apple Health data from an iPhone companion to a self-hosted receiver, then exposes it to AI agents through read-only MCP and CLI queries. The main path is HealthKit or confirmed on-device export import, batch/outbox delivery, receiver acceptance and SQLite storage, then read-only access. The graph also preserves the documented mailbox option and major data lanes. Some links are supported only by the README or SOURCE INDEX; unsampled implementation details are not inferred.

Main entry points: [`ios/HealthBridgeCompanion/App/HealthBridgeCompanionViewModel.swift`](https://github.com/mwdearing/health-relay/blob/main/ios/HealthBridgeCompanion/App/HealthBridgeCompanionViewModel.swift) (Companion UI and sync), [`src/health_bridge/receiver/server.py`](https://github.com/mwdearing/health-relay/blob/main/src/health_bridge/receiver/server.py) (Receiver HTTP service), [`src/health_bridge/storage/database.py`](https://github.com/mwdearing/health-relay/blob/main/src/health_bridge/storage/database.py) (SQLite database), [`ios/HealthBridgeCompanion/Sources/HealthBridgeCompanionCore`](https://github.com/mwdearing/health-relay/tree/main/ios/HealthBridgeCompanion/Sources/HealthBridgeCompanionCore) (Health data readers)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_phone["iPhone companion"]
  node_companion["Companion UI and sync"]
  node_healthread["Health data readers"]
  node_batch["Batch factories"]
  node_labimport["Export lab importer"]
  node_review["Import review"]
end

subgraph group_delivery["Delivery and pairing"]
  node_outbox[("File outbox<br/>[FileOutbox.swift]")]
  node_uploader["Background uploader"]
  node_receiverclient["Receiver client"]
  node_mailbox["Mailbox transport"]
end

subgraph group_receiver["Receiver and storage"]
  node_receiver["Receiver HTTP service<br/>[server.py]"]
  node_acceptance["Batch acceptance"]
  node_ingest["Batch ingestion<br/>[ingest.py]"]
  node_storage[("SQLite database<br/>[database.py]")]
end

subgraph group_access["Read-only access"]
  node_cli["CLI queries<br/>[cli_query.py]"]
  node_query["Health queries"]
  node_mcp["Read-only MCP<br/>[server.py]"]
  node_mcptools["MCP query tools<br/>[tools.py]"]
end

node_person(("iPhone owner"))
node_agent(("AI agent"))
node_healthkit[("Apple HealthKit")]

node_person -->|"uses"| node_companion
node_healthkit -->|"provides data"| node_healthread
node_companion -.->|"reads"| node_healthread
node_healthread -.->|"builds batches"| node_batch
node_companion -->|"imports export"| node_labimport
node_labimport -->|"presents counts"| node_review
node_review -->|"confirms send"| node_companion
node_companion -->|"queues batches"| node_outbox
node_uploader -->|"schedules uploads"| node_outbox
node_companion -->|"pairs and uploads"| node_receiverclient
node_receiverclient -->|"sends privately"| node_receiver
node_outbox -.->|"optional delivery"| node_mailbox
node_mailbox -.->|"delivers via iCloud"| node_receiver
node_receiver -->|"routes requests"| node_acceptance
node_acceptance -.->|"accepts batches"| node_ingest
node_receiver -->|"uses database"| node_storage
node_ingest -->|"writes records"| node_storage
node_agent -->|"requests tools"| node_mcp
node_mcp -->|"dispatches calls"| node_mcptools
node_cli -->|"runs queries"| node_query
node_query -.->|"reads data"| node_storage
node_mcptools -.->|"reads data"| node_storage

click node_companion "https://github.com/mwdearing/health-relay/blob/main/ios/HealthBridgeCompanion/App/HealthBridgeCompanionViewModel.swift"
click node_healthread "https://github.com/mwdearing/health-relay/tree/main/ios/HealthBridgeCompanion/Sources/HealthBridgeCompanionCore"
click node_batch "https://github.com/mwdearing/health-relay/tree/main/ios/HealthBridgeCompanion/Sources/HealthBridgeCompanionCore"
click node_labimport "https://github.com/mwdearing/health-relay/blob/main/ios/HealthBridgeCompanion/Sources/HealthBridgeCompanionCore/AppleHealthExportLabImporter.swift"
click node_review "https://github.com/mwdearing/health-relay/blob/main/ios/HealthBridgeCompanion/App/ExportImportReviewView.swift"
click node_outbox "https://github.com/mwdearing/health-relay/blob/main/ios/HealthBridgeCompanion/Sources/HealthBridgeCompanionCore/FileOutbox.swift"
click node_uploader "https://github.com/mwdearing/health-relay/blob/main/ios/HealthBridgeCompanion/App/BackgroundURLSessionOutboxUploader.swift"
click node_receiverclient "https://github.com/mwdearing/health-relay/blob/main/ios/HealthBridgeCompanion/Sources/HealthBridgeCompanionCore/ReceiverClient.swift"
click node_mailbox "https://github.com/mwdearing/health-relay/blob/main/ios/HealthBridgeCompanion/Sources/HealthBridgeCompanionCore/MailboxTransport.swift"
click node_receiver "https://github.com/mwdearing/health-relay/blob/main/src/health_bridge/receiver/server.py"
click node_acceptance "https://github.com/mwdearing/health-relay/blob/main/src/health_bridge/receiver/batch_acceptance.py"
click node_ingest "https://github.com/mwdearing/health-relay/blob/main/src/health_bridge/ingest.py"
click node_storage "https://github.com/mwdearing/health-relay/blob/main/src/health_bridge/storage/database.py"
click node_cli "https://github.com/mwdearing/health-relay/blob/main/src/health_bridge/cli_query.py"
click node_query "https://github.com/mwdearing/health-relay/tree/main/src/health_bridge/queries"
click node_mcp "https://github.com/mwdearing/health-relay/blob/main/src/health_bridge/mcp/server.py"
click node_mcptools "https://github.com/mwdearing/health-relay/blob/main/src/health_bridge/mcp/tools.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_companion,node_healthread,node_batch,node_labimport,node_review toneBlue
class node_outbox,node_uploader,node_receiverclient,node_mailbox,node_healthkit toneAmber
class node_receiver,node_acceptance,node_ingest,node_storage toneMint
class node_cli,node_query,node_mcp,node_mcptools toneRose
class node_person,node_agent toneIndigo
```

## Components

### iPhone companion

- [Companion UI and sync](https://github.com/mwdearing/health-relay/blob/main/ios/HealthBridgeCompanion/App/HealthBridgeCompanionViewModel.swift): `ios/HealthBridgeCompanion/App/HealthBridgeCompanionViewModel.swift`
- [Health data readers](https://github.com/mwdearing/health-relay/tree/main/ios/HealthBridgeCompanion/Sources/HealthBridgeCompanionCore): `ios/HealthBridgeCompanion/Sources/HealthBridgeCompanionCore`
- [Batch factories](https://github.com/mwdearing/health-relay/tree/main/ios/HealthBridgeCompanion/Sources/HealthBridgeCompanionCore): `ios/HealthBridgeCompanion/Sources/HealthBridgeCompanionCore`
- [Export lab importer](https://github.com/mwdearing/health-relay/blob/main/ios/HealthBridgeCompanion/Sources/HealthBridgeCompanionCore/AppleHealthExportLabImporter.swift): `ios/HealthBridgeCompanion/Sources/HealthBridgeCompanionCore/AppleHealthExportLabImporter.swift`
- [Import review](https://github.com/mwdearing/health-relay/blob/main/ios/HealthBridgeCompanion/App/ExportImportReviewView.swift): `ios/HealthBridgeCompanion/App/ExportImportReviewView.swift`

### Delivery and pairing

- [File outbox](https://github.com/mwdearing/health-relay/blob/main/ios/HealthBridgeCompanion/Sources/HealthBridgeCompanionCore/FileOutbox.swift): `ios/HealthBridgeCompanion/Sources/HealthBridgeCompanionCore/FileOutbox.swift`
- [Background uploader](https://github.com/mwdearing/health-relay/blob/main/ios/HealthBridgeCompanion/App/BackgroundURLSessionOutboxUploader.swift): `ios/HealthBridgeCompanion/App/BackgroundURLSessionOutboxUploader.swift`
- [Receiver client](https://github.com/mwdearing/health-relay/blob/main/ios/HealthBridgeCompanion/Sources/HealthBridgeCompanionCore/ReceiverClient.swift): `ios/HealthBridgeCompanion/Sources/HealthBridgeCompanionCore/ReceiverClient.swift`
- [Mailbox transport](https://github.com/mwdearing/health-relay/blob/main/ios/HealthBridgeCompanion/Sources/HealthBridgeCompanionCore/MailboxTransport.swift): `ios/HealthBridgeCompanion/Sources/HealthBridgeCompanionCore/MailboxTransport.swift`

### Receiver and storage

- [Receiver HTTP service](https://github.com/mwdearing/health-relay/blob/main/src/health_bridge/receiver/server.py): `src/health_bridge/receiver/server.py`
- [Batch acceptance](https://github.com/mwdearing/health-relay/blob/main/src/health_bridge/receiver/batch_acceptance.py): `src/health_bridge/receiver/batch_acceptance.py`
- [Batch ingestion](https://github.com/mwdearing/health-relay/blob/main/src/health_bridge/ingest.py): `src/health_bridge/ingest.py`
- [SQLite database](https://github.com/mwdearing/health-relay/blob/main/src/health_bridge/storage/database.py): `src/health_bridge/storage/database.py`

### Read-only access

- [CLI queries](https://github.com/mwdearing/health-relay/blob/main/src/health_bridge/cli_query.py): `src/health_bridge/cli_query.py`
- [Health queries](https://github.com/mwdearing/health-relay/tree/main/src/health_bridge/queries): `src/health_bridge/queries`
- [Read-only MCP](https://github.com/mwdearing/health-relay/blob/main/src/health_bridge/mcp/server.py): `src/health_bridge/mcp/server.py`
- [MCP query tools](https://github.com/mwdearing/health-relay/blob/main/src/health_bridge/mcp/tools.py): `src/health_bridge/mcp/tools.py`

### Other components

- **iPhone owner**
- **AI agent**
- **Apple HealthKit**

## Connections

- iPhone owner → Companion UI and sync: uses (evidence: `README.md`)
- Apple HealthKit → Health data readers: provides data (evidence: `README.md`)
- Companion UI and sync → Health data readers: reads (evidence: `ios/HealthBridgeCompanion/App/HealthBridgeCompanionViewModel.swift`)
- Health data readers → Batch factories: builds batches
- Companion UI and sync → Export lab importer: imports export (evidence: `ios/HealthBridgeCompanion/App/HealthBridgeCompanionViewModel.swift`)
- Export lab importer → Import review: presents counts (evidence: `ios/HealthBridgeCompanion/App/ExportImportReviewView.swift`)
- Import review → Companion UI and sync: confirms send (evidence: `README.md`)
- Companion UI and sync → File outbox: queues batches (evidence: `ios/HealthBridgeCompanion/App/HealthBridgeCompanionViewModel.swift`)
- Background uploader → File outbox: schedules uploads (evidence: `ios/HealthBridgeCompanion/App/BackgroundURLSessionOutboxUploader.swift`)
- Companion UI and sync → Receiver client: pairs and uploads (evidence: `ios/HealthBridgeCompanion/App/HealthBridgeCompanionViewModel.swift`)
- Receiver client → Receiver HTTP service: sends privately (evidence: `README.md`)
- File outbox → Mailbox transport: optional delivery (evidence: `README.md`)
- Mailbox transport → Receiver HTTP service: delivers via iCloud (evidence: `README.md`)
- Receiver HTTP service → Batch acceptance: routes requests (evidence: `src/health_bridge/receiver/server.py`)
- Batch acceptance → Batch ingestion: accepts batches
- Receiver HTTP service → SQLite database: uses database (evidence: `src/health_bridge/receiver/server.py`)
- Batch ingestion → SQLite database: writes records (evidence: `src/health_bridge/ingest.py`)
- AI agent → Read-only MCP: requests tools (evidence: `README.md`)
- Read-only MCP → MCP query tools: dispatches calls (evidence: `src/health_bridge/mcp/server.py`)
- CLI queries → Health queries: runs queries (evidence: `src/health_bridge/cli_query.py`)
- Health queries → SQLite database: reads data
- MCP query tools → SQLite database: reads data (evidence: `src/health_bridge/mcp/tools.py`)
