# fossasia/voxbento architecture

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

- Interactive diagram: https://gitdiagram.com/fossasia/voxbento
- Repository: https://github.com/fossasia/voxbento

## Overview

VoxBento is a browser-first live interpretation and audio-broadcast platform. Event organizers configure rooms and language booths; interpreters publish audio, attendees listen, and optional AI services generate captions, translations, and speech. The README describes media flowing through MediaMTX rather than Python, with FastAPI handling coordination. The graph preserves documented product capabilities and source-index-supported connections; unsampled modules are represented at their exact paths, and uncertain wiring is omitted.

Main entry points: [`portal/program_ingest.py`](https://github.com/fossasia/voxbento/blob/dev/portal/program_ingest.py) (Program ingest control), [`portal/transcription/worker.py`](https://github.com/fossasia/voxbento/blob/dev/portal/transcription/worker.py) (Transcription workers), [`portal/transcription/aggregator.py`](https://github.com/fossasia/voxbento/blob/dev/portal/transcription/aggregator.py) (Translation aggregation), [`portal/database.py`](https://github.com/fossasia/voxbento/blob/dev/portal/database.py) (Portal database)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Portal and access"]
  node_app["FastAPI application<br/>[fastapi_app.py]"]
  node_authroutes["Authentication routes<br/>[auth.py]"]
  node_auth["Authentication and roles<br/>[auth.py]"]
end

subgraph group_event["Event operations"]
  node_eventops["Event and room operations<br/>[admin.py]"]
  node_database[("Portal database<br/>[database.py]")]
  node_booth["Interpreter booth"]
  node_boothid["Booth identity<br/>[booth_identity.py]"]
end

subgraph group_media["Live media"]
  node_programui["Program ingest UI<br/>[program-ingest.js]"]
  node_ingestroutes["Ingest routes<br/>[program_ingest.py]"]
  node_ingest["Program ingest control<br/>[program_ingest.py]"]
  node_mediamtx["MediaMTX"]
  node_listeners["Listener playback<br/>[listener-event.js]"]
  node_relay["YouTube relay<br/>[program_relay.py]"]
end

subgraph group_ai["AI services"]
  node_transcription["Transcription workers<br/>[worker.py]"]
  node_providers["Speech providers<br/>[base.py]"]
  node_translation["Translation aggregation<br/>[aggregator.py]"]
  node_tts["Speech synthesis<br/>[worker.py]"]
end

subgraph group_coord["Coordination"]
  node_websocket["WebSocket coordination<br/>[manager.py]"]
  node_handlers["WebSocket handlers<br/>[handlers.py]"]
  node_webhooks["Webhook delivery<br/>[worker.py]"]
end

node_organizer(("Event organizer"))
node_interpreter(("Interpreter"))
node_attendee(("Attendee"))

node_organizer -->|"configures event"| node_app
node_interpreter -->|"publishes audio"| node_booth
node_attendee -->|"plays audio"| node_listeners
node_app -->|"registers routes"| node_authroutes
node_authroutes -->|"authenticates"| node_auth
node_eventops -->|"checks access"| node_auth
node_eventops -->|"reads and writes"| node_database
node_ingestroutes -->|"dispatches changes"| node_ingest
node_ingest -->|"controls paths"| node_mediamtx
node_programui -.->|"requests ingest"| node_ingestroutes
node_ingest -->|"updates state"| node_database
node_mediamtx -->|"streams audio"| node_attendee
node_mediamtx -->|"supplies floor audio"| node_transcription
node_transcription -->|"selects provider"| node_providers
node_providers -->|"submits text"| node_translation
node_translation -.->|"delivers captions"| node_attendee
node_translation -.->|"synthesizes speech"| node_tts
node_tts -->|"streams speech"| node_attendee
node_handlers -->|"manages connections"| node_websocket
node_websocket -->|"coordinates booth"| node_interpreter
node_transcription -->|"queues events"| node_webhooks
node_webhooks -->|"loads deliveries"| node_database
node_ingest -->|"configures relay"| node_relay
node_relay -.->|"forwards stream"| node_mediamtx

click node_app "https://github.com/fossasia/voxbento/blob/dev/fastapi_app.py"
click node_authroutes "https://github.com/fossasia/voxbento/blob/dev/portal/routers/auth.py"
click node_auth "https://github.com/fossasia/voxbento/blob/dev/portal/auth.py"
click node_eventops "https://github.com/fossasia/voxbento/blob/dev/portal/routers/admin.py"
click node_database "https://github.com/fossasia/voxbento/blob/dev/portal/database.py"
click node_booth "https://github.com/fossasia/voxbento/blob/dev/portal/static/js/interpreter-booth.js"
click node_boothid "https://github.com/fossasia/voxbento/blob/dev/portal/booth_identity.py"
click node_programui "https://github.com/fossasia/voxbento/blob/dev/portal/static/js/program-ingest.js"
click node_ingestroutes "https://github.com/fossasia/voxbento/blob/dev/portal/routers/program_ingest.py"
click node_ingest "https://github.com/fossasia/voxbento/blob/dev/portal/program_ingest.py"
click node_listeners "https://github.com/fossasia/voxbento/blob/dev/portal/static/js/listener-event.js"
click node_relay "https://github.com/fossasia/voxbento/blob/dev/portal/program_relay.py"
click node_transcription "https://github.com/fossasia/voxbento/blob/dev/portal/transcription/worker.py"
click node_providers "https://github.com/fossasia/voxbento/blob/dev/portal/transcription/providers/base.py"
click node_translation "https://github.com/fossasia/voxbento/blob/dev/portal/transcription/aggregator.py"
click node_tts "https://github.com/fossasia/voxbento/blob/dev/portal/tts/worker.py"
click node_websocket "https://github.com/fossasia/voxbento/blob/dev/portal/websockets/manager.py"
click node_handlers "https://github.com/fossasia/voxbento/blob/dev/portal/websockets/handlers.py"
click node_webhooks "https://github.com/fossasia/voxbento/blob/dev/portal/webhooks/worker.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_authroutes,node_auth toneBlue
class node_eventops,node_database,node_booth,node_boothid toneAmber
class node_programui,node_ingestroutes,node_ingest,node_mediamtx,node_listeners,node_relay toneMint
class node_transcription,node_providers,node_translation,node_tts toneRose
class node_websocket,node_handlers,node_webhooks,node_organizer,node_interpreter,node_attendee toneIndigo
```

## Components

### Portal and access

- [FastAPI application](https://github.com/fossasia/voxbento/blob/dev/fastapi_app.py): `fastapi_app.py`
- [Authentication routes](https://github.com/fossasia/voxbento/blob/dev/portal/routers/auth.py): `portal/routers/auth.py`
- [Authentication and roles](https://github.com/fossasia/voxbento/blob/dev/portal/auth.py): `portal/auth.py`

### Event operations

- [Event and room operations](https://github.com/fossasia/voxbento/blob/dev/portal/routers/admin.py): `portal/routers/admin.py`
- [Portal database](https://github.com/fossasia/voxbento/blob/dev/portal/database.py): `portal/database.py`
- [Interpreter booth](https://github.com/fossasia/voxbento/blob/dev/portal/static/js/interpreter-booth.js): `portal/static/js/interpreter-booth.js`
- [Booth identity](https://github.com/fossasia/voxbento/blob/dev/portal/booth_identity.py): `portal/booth_identity.py`

### Live media

- [Program ingest UI](https://github.com/fossasia/voxbento/blob/dev/portal/static/js/program-ingest.js): `portal/static/js/program-ingest.js`
- [Ingest routes](https://github.com/fossasia/voxbento/blob/dev/portal/routers/program_ingest.py): `portal/routers/program_ingest.py`
- [Program ingest control](https://github.com/fossasia/voxbento/blob/dev/portal/program_ingest.py): `portal/program_ingest.py`
- **MediaMTX**
- [Listener playback](https://github.com/fossasia/voxbento/blob/dev/portal/static/js/listener-event.js): `portal/static/js/listener-event.js`
- [YouTube relay](https://github.com/fossasia/voxbento/blob/dev/portal/program_relay.py): `portal/program_relay.py`

### AI services

- [Transcription workers](https://github.com/fossasia/voxbento/blob/dev/portal/transcription/worker.py): `portal/transcription/worker.py`
- [Speech providers](https://github.com/fossasia/voxbento/blob/dev/portal/transcription/providers/base.py): `portal/transcription/providers/base.py`
- [Translation aggregation](https://github.com/fossasia/voxbento/blob/dev/portal/transcription/aggregator.py): `portal/transcription/aggregator.py`
- [Speech synthesis](https://github.com/fossasia/voxbento/blob/dev/portal/tts/worker.py): `portal/tts/worker.py`

### Coordination

- [WebSocket coordination](https://github.com/fossasia/voxbento/blob/dev/portal/websockets/manager.py): `portal/websockets/manager.py`
- [WebSocket handlers](https://github.com/fossasia/voxbento/blob/dev/portal/websockets/handlers.py): `portal/websockets/handlers.py`
- [Webhook delivery](https://github.com/fossasia/voxbento/blob/dev/portal/webhooks/worker.py): `portal/webhooks/worker.py`

### Other components

- **Event organizer**
- **Interpreter**
- **Attendee**

## Connections

- Event organizer → FastAPI application: configures event (evidence: `README.md`)
- Interpreter → Interpreter booth: publishes audio (evidence: `README.md`)
- Attendee → Listener playback: plays audio (evidence: `README.md`)
- FastAPI application → Authentication routes: registers routes (evidence: `fastapi_app.py`)
- Authentication routes → Authentication and roles: authenticates (evidence: `portal/routers/auth.py`)
- Event and room operations → Authentication and roles: checks access
- Event and room operations → Portal database: reads and writes
- Ingest routes → Program ingest control: dispatches changes (evidence: `portal/routers/program_ingest.py`)
- Program ingest control → MediaMTX: controls paths (evidence: `portal/program_ingest.py`)
- Program ingest UI → Ingest routes: requests ingest
- Program ingest control → Portal database: updates state (evidence: `portal/program_ingest.py`)
- MediaMTX → Attendee: streams audio (evidence: `README.md`)
- MediaMTX → Transcription workers: supplies floor audio (evidence: `README.md`)
- Transcription workers → Speech providers: selects provider (evidence: `portal/transcription/worker.py`)
- Speech providers → Translation aggregation: submits text (evidence: `portal/transcription/providers/base.py`)
- Translation aggregation → Attendee: delivers captions
- Translation aggregation → Speech synthesis: synthesizes speech
- Speech synthesis → Attendee: streams speech (evidence: `README.md`)
- WebSocket handlers → WebSocket coordination: manages connections (evidence: `portal/websockets/handlers.py`)
- WebSocket coordination → Interpreter: coordinates booth (evidence: `README.md`)
- Transcription workers → Webhook delivery: queues events (evidence: `portal/transcription/worker.py`)
- Webhook delivery → Portal database: loads deliveries (evidence: `portal/webhooks/worker.py`)
- Program ingest control → YouTube relay: configures relay (evidence: `portal/program_ingest.py`)
- YouTube relay → MediaMTX: forwards stream