# probablyapigeon/ellie-s-voice-lab architecture

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

- Interactive diagram: https://gitdiagram.com/probablyapigeon/ellie-s-voice-lab
- Repository: https://github.com/probablyapigeon/ellie-s-voice-lab

## Overview

Bird Voice Lab is a local research notebook with a separate synthetic-agent sandbox. The principal workflow is to define an immutable study protocol, commit predictions before a trial, record the observation, then review descriptive comparisons and export evidence. The browser UI calls the local Python server, which dispatches requests to the lab logic and stores study events in SQLite. The README documents major analysis and privacy behavior; several internal implementations and routes were not fully sampled, so those links are omitted where their callers are not shown.

Main entry points: [`app.py`](https://github.com/probablyapigeon/ellie-s-voice-lab/blob/main/app.py) (Local HTTP server), [`lab.py`](https://github.com/probablyapigeon/ellie-s-voice-lab/blob/main/lab.py) (Observation record), [`web/app.js`](https://github.com/probablyapigeon/ellie-s-voice-lab/blob/main/web/app.js) (Notebook interface)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["Browser experience"]
  node_browser_ui["Notebook interface<br/>[app.js]"]
  node_local_server["Local HTTP server<br/>[app.py]"]
end

subgraph group_research["Observation workflow"]
  node_study_protocol["Study protocol<br/>[lab.py]"]
  node_trial_design["Trial predictions<br/>[lab.py]"]
  node_observation["Observation record<br/>[lab.py]"]
  node_stopping_rules["Study stopping<br/>[lab.py]"]
end

subgraph group_engine["Analysis and simulation"]
  node_comparison_controls["Comparison controls<br/>[lab.py]"]
  node_scoring["Descriptive scoring<br/>[lab.py]"]
  node_agent_sandbox["Agent simulation<br/>[lab.py]"]
end

subgraph group_records["Local records"]
  node_event_log["Hash-chained events<br/>[lab.py]"]
  node_sqlite_store[("SQLite store<br/>[lab.py]")]
  node_evidence_export["Evidence exports<br/>[app.py]"]
  node_integrity_check["Export verification<br/>[lab.py]"]
end

node_researcher(("Researcher"))

node_researcher -->|"uses"| node_browser_ui
node_browser_ui -->|"sends API requests"| node_local_server
node_local_server -->|"serves interface"| node_browser_ui
node_local_server -->|"creates studies"| node_study_protocol
node_local_server -->|"commits trials"| node_trial_design
node_local_server -->|"records observations"| node_observation
node_local_server -->|"runs simulation"| node_agent_sandbox
node_local_server -->|"verifies exports"| node_integrity_check
node_study_protocol -->|"appends study"| node_event_log
node_trial_design -->|"locks predictions"| node_comparison_controls
node_observation -->|"scores completed trials"| node_scoring
node_observation -->|"applies end rules"| node_stopping_rules
node_event_log -->|"writes events"| node_sqlite_store
node_local_server -->|"exports JSON and CSV"| node_evidence_export
node_evidence_export -->|"checks receipt"| node_integrity_check
node_researcher -->|"configures sandbox"| node_agent_sandbox

click node_browser_ui "https://github.com/probablyapigeon/ellie-s-voice-lab/blob/main/web/app.js"
click node_local_server "https://github.com/probablyapigeon/ellie-s-voice-lab/blob/main/app.py"
click node_study_protocol "https://github.com/probablyapigeon/ellie-s-voice-lab/blob/main/lab.py"
click node_trial_design "https://github.com/probablyapigeon/ellie-s-voice-lab/blob/main/lab.py"
click node_observation "https://github.com/probablyapigeon/ellie-s-voice-lab/blob/main/lab.py"
click node_stopping_rules "https://github.com/probablyapigeon/ellie-s-voice-lab/blob/main/lab.py"
click node_comparison_controls "https://github.com/probablyapigeon/ellie-s-voice-lab/blob/main/lab.py"
click node_scoring "https://github.com/probablyapigeon/ellie-s-voice-lab/blob/main/lab.py"
click node_agent_sandbox "https://github.com/probablyapigeon/ellie-s-voice-lab/blob/main/lab.py"
click node_event_log "https://github.com/probablyapigeon/ellie-s-voice-lab/blob/main/lab.py"
click node_sqlite_store "https://github.com/probablyapigeon/ellie-s-voice-lab/blob/main/lab.py"
click node_evidence_export "https://github.com/probablyapigeon/ellie-s-voice-lab/blob/main/app.py"
click node_integrity_check "https://github.com/probablyapigeon/ellie-s-voice-lab/blob/main/lab.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_browser_ui,node_local_server toneBlue
class node_study_protocol,node_trial_design,node_observation,node_stopping_rules toneAmber
class node_comparison_controls,node_scoring,node_agent_sandbox toneMint
class node_event_log,node_sqlite_store,node_evidence_export,node_integrity_check toneRose
class node_researcher toneIndigo
```

## Components

### Browser experience

- [Notebook interface](https://github.com/probablyapigeon/ellie-s-voice-lab/blob/main/web/app.js): `web/app.js`
- [Local HTTP server](https://github.com/probablyapigeon/ellie-s-voice-lab/blob/main/app.py): `app.py`

### Observation workflow

- [Study protocol](https://github.com/probablyapigeon/ellie-s-voice-lab/blob/main/lab.py): `lab.py`
- [Trial predictions](https://github.com/probablyapigeon/ellie-s-voice-lab/blob/main/lab.py): `lab.py`
- [Observation record](https://github.com/probablyapigeon/ellie-s-voice-lab/blob/main/lab.py): `lab.py`
- [Study stopping](https://github.com/probablyapigeon/ellie-s-voice-lab/blob/main/lab.py): `lab.py`

### Analysis and simulation

- [Comparison controls](https://github.com/probablyapigeon/ellie-s-voice-lab/blob/main/lab.py): `lab.py`
- [Descriptive scoring](https://github.com/probablyapigeon/ellie-s-voice-lab/blob/main/lab.py): `lab.py`
- [Agent simulation](https://github.com/probablyapigeon/ellie-s-voice-lab/blob/main/lab.py): `lab.py`

### Local records

- [Hash-chained events](https://github.com/probablyapigeon/ellie-s-voice-lab/blob/main/lab.py): `lab.py`
- [SQLite store](https://github.com/probablyapigeon/ellie-s-voice-lab/blob/main/lab.py): `lab.py`
- [Evidence exports](https://github.com/probablyapigeon/ellie-s-voice-lab/blob/main/app.py): `app.py`
- [Export verification](https://github.com/probablyapigeon/ellie-s-voice-lab/blob/main/lab.py): `lab.py`

### Other components

- **Researcher**

## Connections

- Researcher → Notebook interface: uses (evidence: `README.md`)
- Notebook interface → Local HTTP server: sends API requests (evidence: `web/app.js`)
- Local HTTP server → Notebook interface: serves interface (evidence: `app.py`)
- Local HTTP server → Study protocol: creates studies (evidence: `app.py`)
- Local HTTP server → Trial predictions: commits trials (evidence: `app.py`)
- Local HTTP server → Observation record: records observations (evidence: `app.py`)
- Local HTTP server → Agent simulation: runs simulation (evidence: `app.py`)
- Local HTTP server → Export verification: verifies exports (evidence: `app.py`)
- Study protocol → Hash-chained events: appends study (evidence: `lab.py`)
- Trial predictions → Comparison controls: locks predictions (evidence: `README.md`)
- Observation record → Descriptive scoring: scores completed trials (evidence: `README.md`)
- Observation record → Study stopping: applies end rules (evidence: `README.md`)
- Hash-chained events → SQLite store: writes events (evidence: `lab.py`)
- Local HTTP server → Evidence exports: exports JSON and CSV (evidence: `app.py`)
- Evidence exports → Export verification: checks receipt (evidence: `README.md`)
- Researcher → Agent simulation: configures sandbox (evidence: `README.md`)
