# tomasero/opensleep architecture

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

- Interactive diagram: https://gitdiagram.com/tomasero/opensleep
- Repository: https://github.com/tomasero/opensleep

## Overview

OpenSleep is a deprecated sleep-experiment system spanning an iOS sensing and recording app, a prediction API, a BLE-based recording web app, and a separate data-analysis web app. The principal workflow captures physiological signals, submits them to the prediction service, and uses the resulting sleep-detection flow to support audio prompts and dream recording; experiment data can also be reviewed in the analysis UI. Some subsystems are represented only by the file tree and source index, so links not directly evidenced are omitted.

Main entry points: [`deprecated/data_webapp/src/App.js`](https://github.com/tomasero/opensleep/blob/master/deprecated/data_webapp/src/App.js) (Data Review UI), [`deprecated/mobile_app/openSleep/ViewController.swift`](https://github.com/tomasero/opensleep/blob/master/deprecated/mobile_app/openSleep/ViewController.swift) (Sleep Experiment UI), [`deprecated/prediction_server/app.py`](https://github.com/tomasero/opensleep/blob/master/deprecated/prediction_server/app.py) (Prediction API), [`deprecated/mobile_app/openSleep/FlowViewController.swift`](https://github.com/tomasero/opensleep/blob/master/deprecated/mobile_app/openSleep/FlowViewController.swift) (Experiment Flow)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_mobile["iOS Sleep App"]
  node_mobile_ui["Sleep Experiment UI"]
  node_flow_ui["Experiment Flow"]
  node_signal_analysis["Signal Analyzers<br/>[FlexAnalyzer.swift]"]
  node_heart_queue["Heart-Rate Queue<br/>[HeartQueue.swift]"]
  node_sleep_api["Sleep API Client<br/>[SleepAPI.swift]"]
  node_recordings["Audio Recordings<br/>[Recordings.swift]"]
end

subgraph group_prediction["Prediction Service"]
  node_prediction_api["Prediction API<br/>[app.py]"]
  node_feature_processing["Feature Processing<br/>[features.py]"]
  node_classifiers["Classifiers<br/>[classifiers.py]"]
  node_session_data[("Session Data<br/>[config.py]")]
end

subgraph group_ble["BLE Recording"]
  node_ble_web_app["BLE Capture Server<br/>[app.js]"]
  node_rfduino_profile["RFduino Profile<br/>[rfduino.js]"]
  node_noble["BLE Central Library<br/>[noble.js]"]
  node_ble_service["BLE Service Discovery<br/>[service.js]"]
end

subgraph group_analysis["Data Review"]
  node_review_app["Data Review UI<br/>[App.js]"]
  node_session_input["Session Selection<br/>[dataInput.js]"]
  node_graphs["Session Graphs<br/>[graph.js]"]
  node_chart_renderer["Chart Renderer<br/>[canvasjs.react.js]"]
  node_experiment_params["Experiment Parameters"]
  node_upload_modal["Local Data Upload<br/>[uploadModal.js]"]
end

node_user(("Experimenter"))

node_user -->|"operates"| node_mobile_ui
node_mobile_ui -->|"requests predictions"| node_sleep_api
node_mobile_ui -->|"queues heart rate"| node_heart_queue
node_mobile_ui -->|"checks false positives"| node_signal_analysis
node_mobile_ui -->|"controls playback"| node_recordings
node_flow_ui -->|"uploads signals"| node_sleep_api
node_flow_ui -->|"queues heart rate"| node_heart_queue
node_flow_ui -->|"calibrates signals"| node_signal_analysis
node_flow_ui -->|"records dreams"| node_recordings
node_sleep_api -.->|"sends requests"| node_prediction_api
node_prediction_api -->|"extracts features"| node_feature_processing
node_prediction_api -->|"uses classifiers"| node_classifiers
node_prediction_api -->|"reads and writes"| node_session_data
node_user -->|"starts capture"| node_ble_web_app
node_ble_web_app -->|"scans devices"| node_noble
node_ble_web_app -->|"matches service"| node_rfduino_profile
node_ble_web_app -.->|"writes sensor data"| node_session_data
node_ble_service -->|"requests discovery"| node_noble
node_user -->|"selects session"| node_review_app
node_review_app -->|"renders selector"| node_session_input
node_review_app -->|"renders plots"| node_graphs
node_graphs -->|"renders charts"| node_chart_renderer
node_review_app -->|"shows parameters"| node_experiment_params
node_review_app -->|"offers local upload"| node_upload_modal
node_review_app -.->|"fetches session reports"| node_prediction_api

click node_mobile_ui "https://github.com/tomasero/opensleep/blob/master/deprecated/mobile_app/openSleep/ViewController.swift"
click node_flow_ui "https://github.com/tomasero/opensleep/blob/master/deprecated/mobile_app/openSleep/FlowViewController.swift"
click node_signal_analysis "https://github.com/tomasero/opensleep/blob/master/deprecated/mobile_app/openSleep/FlexAnalyzer.swift"
click node_heart_queue "https://github.com/tomasero/opensleep/blob/master/deprecated/mobile_app/openSleep/HeartQueue.swift"
click node_sleep_api "https://github.com/tomasero/opensleep/blob/master/deprecated/mobile_app/openSleep/SleepAPI.swift"
click node_recordings "https://github.com/tomasero/opensleep/blob/master/deprecated/mobile_app/openSleep/Recordings.swift"
click node_prediction_api "https://github.com/tomasero/opensleep/blob/master/deprecated/prediction_server/app.py"
click node_feature_processing "https://github.com/tomasero/opensleep/blob/master/deprecated/prediction_server/features.py"
click node_classifiers "https://github.com/tomasero/opensleep/blob/master/deprecated/prediction_server/classifiers.py"
click node_session_data "https://github.com/tomasero/opensleep/blob/master/deprecated/prediction_server/config.py"
click node_ble_web_app "https://github.com/tomasero/opensleep/blob/master/deprecated/web_app/app.js"
click node_rfduino_profile "https://github.com/tomasero/opensleep/blob/master/deprecated/web_app/rfduino.js"
click node_noble "https://github.com/tomasero/opensleep/blob/master/deprecated/noble/lib/noble.js"
click node_ble_service "https://github.com/tomasero/opensleep/blob/master/deprecated/noble/lib/service.js"
click node_review_app "https://github.com/tomasero/opensleep/blob/master/deprecated/data_webapp/src/App.js"
click node_session_input "https://github.com/tomasero/opensleep/blob/master/deprecated/data_webapp/src/dataInput.js"
click node_graphs "https://github.com/tomasero/opensleep/blob/master/deprecated/data_webapp/src/graph.js"
click node_chart_renderer "https://github.com/tomasero/opensleep/blob/master/deprecated/data_webapp/src/canvas/canvasjs.react.js"
click node_experiment_params "https://github.com/tomasero/opensleep/blob/master/deprecated/data_webapp/src/experimentParams.js"
click node_upload_modal "https://github.com/tomasero/opensleep/blob/master/deprecated/data_webapp/src/uploadModal.js"

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_mobile_ui,node_flow_ui,node_signal_analysis,node_heart_queue,node_sleep_api,node_recordings toneBlue
class node_prediction_api,node_feature_processing,node_classifiers,node_session_data toneAmber
class node_ble_web_app,node_rfduino_profile,node_noble,node_ble_service toneMint
class node_review_app,node_session_input,node_graphs,node_chart_renderer,node_experiment_params,node_upload_modal toneRose
class node_user toneIndigo
```

## Components

### iOS Sleep App

- [Sleep Experiment UI](https://github.com/tomasero/opensleep/blob/master/deprecated/mobile_app/openSleep/ViewController.swift): `deprecated/mobile_app/openSleep/ViewController.swift`
- [Experiment Flow](https://github.com/tomasero/opensleep/blob/master/deprecated/mobile_app/openSleep/FlowViewController.swift): `deprecated/mobile_app/openSleep/FlowViewController.swift`
- [Signal Analyzers](https://github.com/tomasero/opensleep/blob/master/deprecated/mobile_app/openSleep/FlexAnalyzer.swift): `deprecated/mobile_app/openSleep/FlexAnalyzer.swift`
- [Heart-Rate Queue](https://github.com/tomasero/opensleep/blob/master/deprecated/mobile_app/openSleep/HeartQueue.swift): `deprecated/mobile_app/openSleep/HeartQueue.swift`
- [Sleep API Client](https://github.com/tomasero/opensleep/blob/master/deprecated/mobile_app/openSleep/SleepAPI.swift): `deprecated/mobile_app/openSleep/SleepAPI.swift`
- [Audio Recordings](https://github.com/tomasero/opensleep/blob/master/deprecated/mobile_app/openSleep/Recordings.swift): `deprecated/mobile_app/openSleep/Recordings.swift`

### Prediction Service

- [Prediction API](https://github.com/tomasero/opensleep/blob/master/deprecated/prediction_server/app.py): `deprecated/prediction_server/app.py`
- [Feature Processing](https://github.com/tomasero/opensleep/blob/master/deprecated/prediction_server/features.py): `deprecated/prediction_server/features.py`
- [Classifiers](https://github.com/tomasero/opensleep/blob/master/deprecated/prediction_server/classifiers.py): `deprecated/prediction_server/classifiers.py`
- [Session Data](https://github.com/tomasero/opensleep/blob/master/deprecated/prediction_server/config.py): `deprecated/prediction_server/config.py`

### BLE Recording

- [BLE Capture Server](https://github.com/tomasero/opensleep/blob/master/deprecated/web_app/app.js): `deprecated/web_app/app.js`
- [RFduino Profile](https://github.com/tomasero/opensleep/blob/master/deprecated/web_app/rfduino.js): `deprecated/web_app/rfduino.js`
- [BLE Central Library](https://github.com/tomasero/opensleep/blob/master/deprecated/noble/lib/noble.js): `deprecated/noble/lib/noble.js`
- [BLE Service Discovery](https://github.com/tomasero/opensleep/blob/master/deprecated/noble/lib/service.js): `deprecated/noble/lib/service.js`

### Data Review

- [Data Review UI](https://github.com/tomasero/opensleep/blob/master/deprecated/data_webapp/src/App.js): `deprecated/data_webapp/src/App.js`
- [Session Selection](https://github.com/tomasero/opensleep/blob/master/deprecated/data_webapp/src/dataInput.js): `deprecated/data_webapp/src/dataInput.js`
- [Session Graphs](https://github.com/tomasero/opensleep/blob/master/deprecated/data_webapp/src/graph.js): `deprecated/data_webapp/src/graph.js`
- [Chart Renderer](https://github.com/tomasero/opensleep/blob/master/deprecated/data_webapp/src/canvas/canvasjs.react.js): `deprecated/data_webapp/src/canvas/canvasjs.react.js`
- [Experiment Parameters](https://github.com/tomasero/opensleep/blob/master/deprecated/data_webapp/src/experimentParams.js): `deprecated/data_webapp/src/experimentParams.js`
- [Local Data Upload](https://github.com/tomasero/opensleep/blob/master/deprecated/data_webapp/src/uploadModal.js): `deprecated/data_webapp/src/uploadModal.js`

### Other components

- **Experimenter**

## Connections

- Experimenter → Sleep Experiment UI: operates
- Sleep Experiment UI → Sleep API Client: requests predictions (evidence: `deprecated/mobile_app/openSleep/ViewController.swift`)
- Sleep Experiment UI → Heart-Rate Queue: queues heart rate (evidence: `deprecated/mobile_app/openSleep/ViewController.swift`)
- Sleep Experiment UI → Signal Analyzers: checks false positives (evidence: `deprecated/mobile_app/openSleep/ViewController.swift`)
- Sleep Experiment UI → Audio Recordings: controls playback (evidence: `deprecated/mobile_app/openSleep/ViewController.swift`)
- Experiment Flow → Sleep API Client: uploads signals (evidence: `deprecated/mobile_app/openSleep/FlowViewController.swift`)
- Experiment Flow → Heart-Rate Queue: queues heart rate (evidence: `deprecated/mobile_app/openSleep/FlowViewController.swift`)
- Experiment Flow → Signal Analyzers: calibrates signals (evidence: `deprecated/mobile_app/openSleep/FlowViewController.swift`)
- Experiment Flow → Audio Recordings: records dreams (evidence: `deprecated/mobile_app/openSleep/FlowViewController.swift`)
- Sleep API Client → Prediction API: sends requests
- Prediction API → Feature Processing: extracts features (evidence: `deprecated/prediction_server/app.py`)
- Prediction API → Classifiers: uses classifiers (evidence: `deprecated/prediction_server/app.py`)
- Prediction API → Session Data: reads and writes (evidence: `deprecated/prediction_server/app.py`)
- Experimenter → BLE Capture Server: starts capture (evidence: `deprecated/web_app/app.js`)
- BLE Capture Server → BLE Central Library: scans devices (evidence: `deprecated/web_app/app.js`)
- BLE Capture Server → RFduino Profile: matches service (evidence: `deprecated/web_app/app.js`)
- BLE Capture Server → Session Data: writes sensor data
- BLE Service Discovery → BLE Central Library: requests discovery (evidence: `deprecated/noble/lib/service.js`)
- Experimenter → Data Review UI: selects session (evidence: `deprecated/data_webapp/src/App.js`)
- Data Review UI → Session Selection: renders selector (evidence: `deprecated/data_webapp/src/App.js`)
- Data Review UI → Session Graphs: renders plots (evidence: `deprecated/data_webapp/src/App.js`)
- Session Graphs → Chart Renderer: renders charts (evidence: `deprecated/data_webapp/src/graph.js`)
- Data Review UI → Experiment Parameters: shows parameters (evidence: `deprecated/data_webapp/src/App.js`)
- Data Review UI → Local Data Upload: offers local upload (evidence: `deprecated/data_webapp/src/App.js`)
- Data Review UI → Prediction API: fetches session reports
