# vladimirfokow/transept architecture

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

- Interactive diagram: https://gitdiagram.com/vladimirfokow/transept
- Repository: https://github.com/vladimirfokow/transept

## Overview

Transept captures meeting audio, turns recognition fragments into sentence-sized captions, translates for languages people are actively reading, and streams each language to phones. The principal runtime is `server.py` in self-hosted mode; hosted mode moves capture to `sender.py` and sends audio to that same server. Recording and offline translation review are separate quality-improvement capabilities. The README and sampled excerpts support the main boundaries; some internal wiring is not shown, so uncertain links are omitted.

Main entry points: [`pipeline.py`](https://github.com/vladimirfokow/transept/blob/main/pipeline.py) (Speech pipeline), [`server.py`](https://github.com/vladimirfokow/transept/blob/main/server.py) (Session server), [`record.py`](https://github.com/vladimirfokow/transept/blob/main/record.py) (Session recorder), [`capture.py`](https://github.com/vladimirfokow/transept/blob/main/capture.py) (Capture backends)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_capture["Audio capture"]
  node_capture["Capture backends<br/>[capture.py]"]
  node_sender["Hosted room sender<br/>[sender.py]"]
end

subgraph group_processing["Recognition and translation"]
  node_pipeline["Speech pipeline<br/>[pipeline.py]"]
  node_deepgram{{"Deepgram"}}
  node_translator{{"Translation provider"}}
end

subgraph group_delivery["Controls and delivery"]
  node_server["Session server<br/>[server.py]"]
  node_operator_ui["Operator page<br/>[operator.html]"]
  node_controls["Operator routes<br/>[controls.py]"]
  node_reader_ui["Reader page<br/>[reader.html]"]
  node_channels["Language streams<br/>[server.py]"]
  node_tailscale{{"Tailscale Funnel"}}
end

subgraph group_quality["Recording and review"]
  node_recording["Session recorder<br/>[record.py]"]
  node_session_db[("Session database<br/>[record.py]")]
  node_review_doc["Review document<br/>[record.py]"]
  node_offline_review["Offline translation review<br/>[review.py]"]
end

node_operator(("Operator"))
node_microphone(("Microphone"))
node_readers(("Phone readers"))

node_microphone -->|"provides audio"| node_capture
node_capture -->|"streams audio"| node_pipeline
node_pipeline -->|"sends audio"| node_deepgram
node_deepgram -->|"returns fragments"| node_pipeline
node_pipeline -->|"requests translations"| node_translator
node_translator -->|"returns translations"| node_pipeline
node_operator -->|"uses"| node_operator_ui
node_operator_ui -->|"calls routes"| node_controls
node_controls -->|"controls session"| node_server
node_server -->|"runs pipeline"| node_pipeline
node_pipeline -->|"publishes captions"| node_channels
node_channels -->|"streams language"| node_reader_ui
node_reader_ui -->|"displays captions"| node_readers
node_server -->|"records session"| node_recording
node_recording -->|"writes session"| node_session_db
node_recording -->|"generates review"| node_review_doc
node_offline_review -.->|"requests translations"| node_translator
node_sender -->|"opens audio source"| node_capture
node_sender -->|"sends audio and controls"| node_server
node_tailscale -.->|"publishes reader access"| node_server

click node_capture "https://github.com/vladimirfokow/transept/blob/main/capture.py"
click node_sender "https://github.com/vladimirfokow/transept/blob/main/sender.py"
click node_server "https://github.com/vladimirfokow/transept/blob/main/server.py"
click node_pipeline "https://github.com/vladimirfokow/transept/blob/main/pipeline.py"
click node_operator_ui "https://github.com/vladimirfokow/transept/blob/main/static/operator.html"
click node_controls "https://github.com/vladimirfokow/transept/blob/main/controls.py"
click node_reader_ui "https://github.com/vladimirfokow/transept/blob/main/static/reader.html"
click node_channels "https://github.com/vladimirfokow/transept/blob/main/server.py"
click node_recording "https://github.com/vladimirfokow/transept/blob/main/record.py"
click node_session_db "https://github.com/vladimirfokow/transept/blob/main/record.py"
click node_review_doc "https://github.com/vladimirfokow/transept/blob/main/record.py"
click node_offline_review "https://github.com/vladimirfokow/transept/blob/main/review.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_capture,node_sender toneBlue
class node_pipeline,node_deepgram,node_translator toneAmber
class node_server,node_operator_ui,node_controls,node_reader_ui,node_channels,node_tailscale toneMint
class node_recording,node_session_db,node_review_doc,node_offline_review toneRose
class node_operator,node_microphone,node_readers toneIndigo
```

## Components

### Audio capture

- [Capture backends](https://github.com/vladimirfokow/transept/blob/main/capture.py): `capture.py`
- [Hosted room sender](https://github.com/vladimirfokow/transept/blob/main/sender.py): `sender.py`

### Recognition and translation

- [Speech pipeline](https://github.com/vladimirfokow/transept/blob/main/pipeline.py): `pipeline.py`
- **Deepgram**
- **Translation provider**

### Controls and delivery

- [Session server](https://github.com/vladimirfokow/transept/blob/main/server.py): `server.py`
- [Operator page](https://github.com/vladimirfokow/transept/blob/main/static/operator.html): `static/operator.html`
- [Operator routes](https://github.com/vladimirfokow/transept/blob/main/controls.py): `controls.py`
- [Reader page](https://github.com/vladimirfokow/transept/blob/main/static/reader.html): `static/reader.html`
- [Language streams](https://github.com/vladimirfokow/transept/blob/main/server.py): `server.py`
- **Tailscale Funnel**

### Recording and review

- [Session recorder](https://github.com/vladimirfokow/transept/blob/main/record.py): `record.py`
- [Session database](https://github.com/vladimirfokow/transept/blob/main/record.py): `record.py`
- [Review document](https://github.com/vladimirfokow/transept/blob/main/record.py): `record.py`
- [Offline translation review](https://github.com/vladimirfokow/transept/blob/main/review.py): `review.py`

### Other components

- **Operator**
- **Microphone**
- **Phone readers**

## Connections

- Microphone → Capture backends: provides audio
- Capture backends → Speech pipeline: streams audio
- Speech pipeline → Deepgram: sends audio
- Deepgram → Speech pipeline: returns fragments
- Speech pipeline → Translation provider: requests translations
- Translation provider → Speech pipeline: returns translations
- Operator → Operator page: uses
- Operator page → Operator routes: calls routes
- Operator routes → Session server: controls session
- Session server → Speech pipeline: runs pipeline
- Speech pipeline → Language streams: publishes captions
- Language streams → Reader page: streams language
- Reader page → Phone readers: displays captions
- Session server → Session recorder: records session
- Session recorder → Session database: writes session
- Session recorder → Review document: generates review
- Offline translation review → Translation provider: requests translations
- Hosted room sender → Capture backends: opens audio source
- Hosted room sender → Session server: sends audio and controls
- Tailscale Funnel → Session server: publishes reader access