# jalen-cheng/eightpod architecture

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

- Interactive diagram: https://gitdiagram.com/jalen-cheng/eightpod
- Repository: https://github.com/jalen-cheng/eightpod

## Overview

EightPod is a local control system for Eight Sleep Pods: a phone-friendly web app talks to a server on the Pod, which controls firmware and exposes a local API. Users adjust temperature and power, configure schedules and alarms, manage settings, and inspect status and available sleep data. The server also monitors device sensors and runs scheduling jobs; a separate biometrics service processes sensor data. The README documents these product capabilities, while sampled source confirms app routing, server route registration and startup, and biometrics service-status updates; several internal control paths are not shown.

Main entry points: [`app/src/main.tsx`](https://github.com/jalen-cheng/eightpod/blob/main/app/src/main.tsx) (Phone web app), [`server/src/server.ts`](https://github.com/jalen-cheng/eightpod/blob/main/server/src/server.ts) (Server runtime), [`server/src/setup/routes.ts`](https://github.com/jalen-cheng/eightpod/blob/main/server/src/setup/routes.ts) (Local API routes), [`server/src/jobs/jobScheduler.ts`](https://github.com/jalen-cheng/eightpod/blob/main/server/src/jobs/jobScheduler.ts) (Job scheduler)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web app"]
  node_app["Phone web app<br/>[main.tsx]"]
  node_temperature["Temperature control"]
  node_schedule_ui["Schedule editor<br/>[SchedulePage.tsx]"]
  node_settings_ui["Settings<br/>[SettingsPage.tsx]"]
  node_data_ui["Sleep and vitals<br/>[DataPage.tsx]"]
  node_status_ui["Device status<br/>[StatusPage.tsx]"]
end

subgraph group_server["Local server"]
  node_api_routes["Local API routes<br/>[routes.ts]"]
  node_server_runtime["Server runtime<br/>[server.ts]"]
  node_settings_store[("Services state<br/>[services.ts]")]
end

subgraph group_device["Pod device"]
  node_device_link["Firmware interface<br/>[frankenServer.ts]"]
  node_sensor_monitor["Sensor monitors"]
end

subgraph group_automation["Schedules and jobs"]
  node_schedules[("Schedules and alarms<br/>[schedules.ts]")]
  node_job_scheduler["Job scheduler<br/>[jobScheduler.ts]"]
end

subgraph group_biometrics["Biometrics"]
  node_biometrics_stream["Sensor processing<br/>[stream.py]"]
  node_sleep_detection["Sleep detection<br/>[sleep_detector.py]"]
  node_vitals["Vitals analysis<br/>[calculations.py]"]
  node_biometrics_api["Health updates<br/>[service_health.py]"]
end

node_user(("Pod user"))

node_user -->|"uses"| node_app
node_app -->|"routes to"| node_temperature
node_app -->|"routes to"| node_schedule_ui
node_app -->|"routes to"| node_settings_ui
node_app -->|"routes to"| node_data_ui
node_app -->|"routes to"| node_status_ui
node_app -.->|"calls local API"| node_api_routes
node_server_runtime -->|"registers"| node_api_routes
node_api_routes -->|"reads and writes"| node_settings_store
node_server_runtime -->|"initializes"| node_device_link
node_server_runtime -->|"starts"| node_sensor_monitor
node_server_runtime -->|"starts"| node_job_scheduler
node_job_scheduler -.->|"executes scheduled work"| node_schedules
node_job_scheduler -.->|"controls firmware"| node_device_link
node_sensor_monitor -.->|"provides sensor data"| node_biometrics_stream
node_biometrics_stream -.->|"supports analysis"| node_sleep_detection
node_biometrics_stream -.->|"supports analysis"| node_vitals
node_biometrics_api -->|"posts health status"| node_api_routes

click node_app "https://github.com/jalen-cheng/eightpod/blob/main/app/src/main.tsx"
click node_temperature "https://github.com/jalen-cheng/eightpod/blob/main/app/src/pages/ControlTempPage/ControlTempPage.tsx"
click node_schedule_ui "https://github.com/jalen-cheng/eightpod/blob/main/app/src/pages/SchedulePage/SchedulePage.tsx"
click node_settings_ui "https://github.com/jalen-cheng/eightpod/blob/main/app/src/pages/SettingsPage/SettingsPage.tsx"
click node_data_ui "https://github.com/jalen-cheng/eightpod/blob/main/app/src/pages/DataPage/DataPage.tsx"
click node_status_ui "https://github.com/jalen-cheng/eightpod/blob/main/app/src/pages/StatusPage/StatusPage.tsx"
click node_api_routes "https://github.com/jalen-cheng/eightpod/blob/main/server/src/setup/routes.ts"
click node_server_runtime "https://github.com/jalen-cheng/eightpod/blob/main/server/src/server.ts"
click node_settings_store "https://github.com/jalen-cheng/eightpod/blob/main/server/src/db/services.ts"
click node_device_link "https://github.com/jalen-cheng/eightpod/blob/main/server/src/8sleep/frankenServer.ts"
click node_sensor_monitor "https://github.com/jalen-cheng/eightpod/blob/main/server/src/8sleep/bedSensorMonitor.ts"
click node_schedules "https://github.com/jalen-cheng/eightpod/blob/main/server/src/db/schedules.ts"
click node_job_scheduler "https://github.com/jalen-cheng/eightpod/blob/main/server/src/jobs/jobScheduler.ts"
click node_biometrics_stream "https://github.com/jalen-cheng/eightpod/blob/main/biometrics/stream/stream.py"
click node_sleep_detection "https://github.com/jalen-cheng/eightpod/blob/main/biometrics/sleep_detection/sleep_detector.py"
click node_vitals "https://github.com/jalen-cheng/eightpod/blob/main/biometrics/vitals/calculations.py"
click node_biometrics_api "https://github.com/jalen-cheng/eightpod/blob/main/biometrics/service_health.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_app,node_temperature,node_schedule_ui,node_settings_ui,node_data_ui,node_status_ui,node_user toneBlue
class node_api_routes,node_server_runtime,node_settings_store toneAmber
class node_device_link,node_sensor_monitor toneMint
class node_schedules,node_job_scheduler toneRose
class node_biometrics_stream,node_sleep_detection,node_vitals,node_biometrics_api toneIndigo
```

## Components

### Web app

- [Phone web app](https://github.com/jalen-cheng/eightpod/blob/main/app/src/main.tsx): `app/src/main.tsx`
- [Temperature control](https://github.com/jalen-cheng/eightpod/blob/main/app/src/pages/ControlTempPage/ControlTempPage.tsx): `app/src/pages/ControlTempPage/ControlTempPage.tsx`
- [Schedule editor](https://github.com/jalen-cheng/eightpod/blob/main/app/src/pages/SchedulePage/SchedulePage.tsx): `app/src/pages/SchedulePage/SchedulePage.tsx`
- [Settings](https://github.com/jalen-cheng/eightpod/blob/main/app/src/pages/SettingsPage/SettingsPage.tsx): `app/src/pages/SettingsPage/SettingsPage.tsx`
- [Sleep and vitals](https://github.com/jalen-cheng/eightpod/blob/main/app/src/pages/DataPage/DataPage.tsx): `app/src/pages/DataPage/DataPage.tsx`
- [Device status](https://github.com/jalen-cheng/eightpod/blob/main/app/src/pages/StatusPage/StatusPage.tsx): `app/src/pages/StatusPage/StatusPage.tsx`

### Local server

- [Local API routes](https://github.com/jalen-cheng/eightpod/blob/main/server/src/setup/routes.ts): `server/src/setup/routes.ts`
- [Server runtime](https://github.com/jalen-cheng/eightpod/blob/main/server/src/server.ts): `server/src/server.ts`
- [Services state](https://github.com/jalen-cheng/eightpod/blob/main/server/src/db/services.ts): `server/src/db/services.ts`

### Pod device

- [Firmware interface](https://github.com/jalen-cheng/eightpod/blob/main/server/src/8sleep/frankenServer.ts): `server/src/8sleep/frankenServer.ts`
- [Sensor monitors](https://github.com/jalen-cheng/eightpod/blob/main/server/src/8sleep/bedSensorMonitor.ts): `server/src/8sleep/bedSensorMonitor.ts`

### Schedules and jobs

- [Schedules and alarms](https://github.com/jalen-cheng/eightpod/blob/main/server/src/db/schedules.ts): `server/src/db/schedules.ts`
- [Job scheduler](https://github.com/jalen-cheng/eightpod/blob/main/server/src/jobs/jobScheduler.ts): `server/src/jobs/jobScheduler.ts`

### Biometrics

- [Sensor processing](https://github.com/jalen-cheng/eightpod/blob/main/biometrics/stream/stream.py): `biometrics/stream/stream.py`
- [Sleep detection](https://github.com/jalen-cheng/eightpod/blob/main/biometrics/sleep_detection/sleep_detector.py): `biometrics/sleep_detection/sleep_detector.py`
- [Vitals analysis](https://github.com/jalen-cheng/eightpod/blob/main/biometrics/vitals/calculations.py): `biometrics/vitals/calculations.py`
- [Health updates](https://github.com/jalen-cheng/eightpod/blob/main/biometrics/service_health.py): `biometrics/service_health.py`

### Other components

- **Pod user**

## Connections

- Pod user → Phone web app: uses (evidence: `README.md`)
- Phone web app → Temperature control: routes to (evidence: `app/src/main.tsx`)
- Phone web app → Schedule editor: routes to (evidence: `app/src/main.tsx`)
- Phone web app → Settings: routes to (evidence: `app/src/main.tsx`)
- Phone web app → Sleep and vitals: routes to (evidence: `app/src/main.tsx`)
- Phone web app → Device status: routes to (evidence: `app/src/main.tsx`)
- Phone web app → Local API routes: calls local API (evidence: `README.md`)
- Server runtime → Local API routes: registers (evidence: `server/src/server.ts`)
- Local API routes → Services state: reads and writes
- Server runtime → Firmware interface: initializes (evidence: `server/src/server.ts`)
- Server runtime → Sensor monitors: starts (evidence: `server/src/server.ts`)
- Server runtime → Job scheduler: starts (evidence: `server/src/server.ts`)
- Job scheduler → Schedules and alarms: executes scheduled work
- Job scheduler → Firmware interface: controls firmware (evidence: `README.md`)
- Sensor monitors → Sensor processing: provides sensor data (evidence: `README.md`)
- Sensor processing → Sleep detection: supports analysis
- Sensor processing → Vitals analysis: supports analysis
- Health updates → Local API routes: posts health status (evidence: `biometrics/service_health.py`)
