# cheiineeey/callhome architecture

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

- Interactive diagram: https://gitdiagram.com/cheiineeey/callhome
- Repository: https://github.com/cheiineeey/callhome

## Overview

Callhome is a self-hosted voice-call stack for AI companions. Its main voice workflow sends browser-recorded audio to the STT service for transcription, emotion tags, and speaker-relative tone cues, then returns the interaction to a gateway that coordinates an LLM and TTS. A separate invite workflow supports companion-initiated calls and PWA push ringing. The repository contains reference extracts rather than the complete gateway or client; several README-documented capabilities have no sampled implementation path, so their links are documentation-based.

Main entry points: [`pwa-reference`](https://github.com/cheiineeey/callhome/tree/main/pwa-reference) (Call UI), [`gateway-reference`](https://github.com/cheiineeey/callhome/tree/main/gateway-reference) (Conversation gateway), [`gateway-reference/markers.js`](https://github.com/cheiineeey/callhome/blob/main/gateway-reference/markers.js) (Marker handler), [`stt-service/server.py`](https://github.com/cheiineeey/callhome/blob/main/stt-service/server.py) (Transcription endpoint)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["PWA ringing"]
  node_pwa["Call UI"]
  node_registration["Worker registration"]
  node_worker["Push worker<br/>[sw.js]"]
  node_cleanup["Ring cleanup"]
end

subgraph group_gateway["Call orchestration"]
  node_gateway["Conversation gateway"]
  node_markers["Marker handler<br/>[markers.js]"]
  node_escalation["Escalation dialer<br/>[escalation.js]"]
  node_invite["Call invite API"]
  node_ringing["Ring burst<br/>[ring-burst.py]"]
end

subgraph group_speech["Speech understanding"]
  node_stt["Transcription endpoint<br/>[server.py]"]
  node_tone[("Tone baseline<br/>[tone.py]")]
  node_emotion["Emotion sensing<br/>[server.py]"]
end

subgraph group_capabilities["Call capabilities"]
  node_hangup["Gentle hangup<br/>[markers.js]"]
  node_dnd["Do not disturb<br/>[markers.js]"]
  node_voicemail["Voicemail<br/>[PROTOCOL.md]"]
  node_decline["Quick decline<br/>[PROTOCOL.md]"]
  node_records["Call records<br/>[PROTOCOL.md]"]
  node_radio["Bedtime radio<br/>[README.md]"]
end

node_person(("Person"))
node_llm["LLM service"]
node_tts["TTS service"]
node_push["Web push"]

node_person -->|"uses"| node_pwa
node_pwa -->|"uploads audio"| node_stt
node_stt -->|"tags speech"| node_emotion
node_stt -->|"ranks features"| node_tone
node_stt -->|"returns transcript"| node_gateway
node_gateway -->|"requests reply"| node_llm
node_gateway -->|"requests speech"| node_tts
node_tts -->|"streams audio"| node_pwa
node_gateway -->|"parses reply"| node_markers
node_markers -->|"creates invite"| node_invite
node_invite -->|"starts burst"| node_ringing
node_ringing -->|"sends notifications"| node_push
node_push -->|"delivers push"| node_worker
node_worker -->|"signals incoming call"| node_pwa
node_pwa -->|"registers worker"| node_registration
node_pwa -->|"stops ringing"| node_cleanup
node_worker -->|"closes notification stack"| node_cleanup
node_escalation -->|"requests invite"| node_invite
node_escalation -->|"generates reason"| node_llm
node_markers -->|"handles marker"| node_hangup
node_markers -->|"updates flag"| node_dnd
node_gateway -->|"supports"| node_voicemail
node_pwa -->|"offers"| node_decline
node_gateway -->|"keeps"| node_records
node_pwa -->|"offers"| node_radio

click node_pwa "https://github.com/cheiineeey/callhome/tree/main/pwa-reference"
click node_registration "https://github.com/cheiineeey/callhome/blob/main/pwa-reference/register-and-clear.js"
click node_worker "https://github.com/cheiineeey/callhome/blob/main/pwa-reference/sw.js"
click node_cleanup "https://github.com/cheiineeey/callhome/blob/main/pwa-reference/register-and-clear.js"
click node_gateway "https://github.com/cheiineeey/callhome/tree/main/gateway-reference"
click node_markers "https://github.com/cheiineeey/callhome/blob/main/gateway-reference/markers.js"
click node_escalation "https://github.com/cheiineeey/callhome/blob/main/gateway-reference/escalation.js"
click node_invite "https://github.com/cheiineeey/callhome/tree/main/gateway-reference"
click node_ringing "https://github.com/cheiineeey/callhome/blob/main/gateway-reference/ring-burst.py"
click node_stt "https://github.com/cheiineeey/callhome/blob/main/stt-service/server.py"
click node_tone "https://github.com/cheiineeey/callhome/blob/main/stt-service/tone.py"
click node_emotion "https://github.com/cheiineeey/callhome/blob/main/stt-service/server.py"
click node_hangup "https://github.com/cheiineeey/callhome/blob/main/gateway-reference/markers.js"
click node_dnd "https://github.com/cheiineeey/callhome/blob/main/gateway-reference/markers.js"
click node_voicemail "https://github.com/cheiineeey/callhome/blob/main/docs/PROTOCOL.md"
click node_decline "https://github.com/cheiineeey/callhome/blob/main/docs/PROTOCOL.md"
click node_records "https://github.com/cheiineeey/callhome/blob/main/docs/PROTOCOL.md"
click node_radio "https://github.com/cheiineeey/callhome/blob/main/README.md"

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_pwa,node_registration,node_worker,node_cleanup toneBlue
class node_gateway,node_markers,node_escalation,node_invite,node_ringing toneAmber
class node_stt,node_tone,node_emotion toneMint
class node_hangup,node_dnd,node_voicemail,node_decline,node_records,node_radio toneRose
class node_person,node_llm,node_tts,node_push toneIndigo
```

## Components

### PWA ringing

- [Call UI](https://github.com/cheiineeey/callhome/tree/main/pwa-reference): `pwa-reference`
- [Worker registration](https://github.com/cheiineeey/callhome/blob/main/pwa-reference/register-and-clear.js): `pwa-reference/register-and-clear.js`
- [Push worker](https://github.com/cheiineeey/callhome/blob/main/pwa-reference/sw.js): `pwa-reference/sw.js`
- [Ring cleanup](https://github.com/cheiineeey/callhome/blob/main/pwa-reference/register-and-clear.js): `pwa-reference/register-and-clear.js`

### Call orchestration

- [Conversation gateway](https://github.com/cheiineeey/callhome/tree/main/gateway-reference): `gateway-reference`
- [Marker handler](https://github.com/cheiineeey/callhome/blob/main/gateway-reference/markers.js): `gateway-reference/markers.js`
- [Escalation dialer](https://github.com/cheiineeey/callhome/blob/main/gateway-reference/escalation.js): `gateway-reference/escalation.js`
- [Call invite API](https://github.com/cheiineeey/callhome/tree/main/gateway-reference): `gateway-reference`
- [Ring burst](https://github.com/cheiineeey/callhome/blob/main/gateway-reference/ring-burst.py): `gateway-reference/ring-burst.py`

### Speech understanding

- [Transcription endpoint](https://github.com/cheiineeey/callhome/blob/main/stt-service/server.py): `stt-service/server.py`
- [Tone baseline](https://github.com/cheiineeey/callhome/blob/main/stt-service/tone.py): `stt-service/tone.py`
- [Emotion sensing](https://github.com/cheiineeey/callhome/blob/main/stt-service/server.py): `stt-service/server.py`

### Call capabilities

- [Gentle hangup](https://github.com/cheiineeey/callhome/blob/main/gateway-reference/markers.js): `gateway-reference/markers.js`
- [Do not disturb](https://github.com/cheiineeey/callhome/blob/main/gateway-reference/markers.js): `gateway-reference/markers.js`
- [Voicemail](https://github.com/cheiineeey/callhome/blob/main/docs/PROTOCOL.md): `docs/PROTOCOL.md`
- [Quick decline](https://github.com/cheiineeey/callhome/blob/main/docs/PROTOCOL.md): `docs/PROTOCOL.md`
- [Call records](https://github.com/cheiineeey/callhome/blob/main/docs/PROTOCOL.md): `docs/PROTOCOL.md`
- [Bedtime radio](https://github.com/cheiineeey/callhome/blob/main/README.md): `README.md`

### Other components

- **Person**
- **LLM service**
- **TTS service**
- **Web push**

## Connections

- Person → Call UI: uses (evidence: `README.md`)
- Call UI → Transcription endpoint: uploads audio (evidence: `README.md`)
- Transcription endpoint → Emotion sensing: tags speech (evidence: `stt-service/server.py`)
- Transcription endpoint → Tone baseline: ranks features (evidence: `stt-service/server.py`)
- Transcription endpoint → Conversation gateway: returns transcript (evidence: `README.md`)
- Conversation gateway → LLM service: requests reply (evidence: `README.md`)
- Conversation gateway → TTS service: requests speech (evidence: `README.md`)
- TTS service → Call UI: streams audio (evidence: `README.md`)
- Conversation gateway → Marker handler: parses reply (evidence: `gateway-reference/markers.js`)
- Marker handler → Call invite API: creates invite (evidence: `gateway-reference/markers.js`)
- Call invite API → Ring burst: starts burst (evidence: `gateway-reference/ring-burst.py`)
- Ring burst → Web push: sends notifications (evidence: `gateway-reference/ring-burst.py`)
- Web push → Push worker: delivers push (evidence: `pwa-reference/sw.js`)
- Push worker → Call UI: signals incoming call (evidence: `pwa-reference/sw.js`)
- Call UI → Worker registration: registers worker (evidence: `pwa-reference/register-and-clear.js`)
- Call UI → Ring cleanup: stops ringing (evidence: `pwa-reference/register-and-clear.js`)
- Push worker → Ring cleanup: closes notification stack (evidence: `pwa-reference/sw.js`)
- Escalation dialer → Call invite API: requests invite (evidence: `gateway-reference/escalation.js`)
- Escalation dialer → LLM service: generates reason (evidence: `gateway-reference/escalation.js`)
- Marker handler → Gentle hangup: handles marker (evidence: `gateway-reference/markers.js`)
- Marker handler → Do not disturb: updates flag (evidence: `gateway-reference/markers.js`)
- Conversation gateway → Voicemail: supports (evidence: `README.md`)
- Call UI → Quick decline: offers (evidence: `README.md`)
- Conversation gateway → Call records: keeps (evidence: `README.md`)
- Call UI → Bedtime radio: offers (evidence: `README.md`)
