# derpeloper/ostinato architecture

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

- Interactive diagram: https://gitdiagram.com/derpeloper/ostinato
- Repository: https://github.com/derpeloper/ostinato

## Overview

Ostinato is a Discord voice bot that turns server messages into speech. The main path is message/event handling through TTS policy and per-server queuing, worker inference, then audio playback in a voice channel; commands also configure voices, language, speed, filters, and other server behavior. Persistent preferences use SQLite, and command text is localized. The README documents the worker-pool and audio pipeline; several runtime files are represented from the source index, so unshown implementation links are omitted where their ownership is unclear.

Main entry points: [`src/services/OstinatoTTS.js`](https://github.com/derpeloper/ostinato/blob/main/src/services/OstinatoTTS.js) (TTS service), [`src/index.js`](https://github.com/derpeloper/ostinato/blob/main/src/index.js) (Bot entry), [`src/services/ttsWorker.js`](https://github.com/derpeloper/ostinato/blob/main/src/services/ttsWorker.js) (TTS workers), [`src/commands/public`](https://github.com/derpeloper/ostinato/tree/main/src/commands/public) (User commands)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Discord runtime"]
  node_entry["Bot entry<br/>[index.js]"]
  node_events["Event handlers"]
end

subgraph group_commands["Commands and settings"]
  node_public_cmds["User commands"]
  node_mod_cmds["Moderator commands"]
end

subgraph group_speech["Speech pipeline"]
  node_tts_service["TTS service<br/>[OstinatoTTS.js]"]
  node_worker["TTS workers<br/>[ttsWorker.js]"]
  node_engine["Supertonic engine<br/>[helper.mjs]"]
  node_text_clean["Text cleanup<br/>[cleanText.js]"]
  node_voice_styles["Voice styles"]
  node_audio["FFmpeg audio"]
end

subgraph group_support["Persistence and language"]
  node_settings["Runtime config<br/>[config.js]"]
  node_database[("SQLite settings<br/>[db.js]")]
  node_localization["Translations<br/>[localize.js]"]
end

node_server_user(("Server user"))
node_discord["Discord"]

node_server_user -->|"sends messages"| node_discord
node_discord -->|"delivers events"| node_entry
node_entry -->|"loads handlers"| node_events
node_entry -->|"initializes"| node_tts_service
node_entry -.->|"loads commands"| node_public_cmds
node_entry -.->|"loads commands"| node_mod_cmds
node_events -->|"requests speech"| node_tts_service
node_public_cmds -->|"reads/writes"| node_database
node_mod_cmds -->|"reads/writes"| node_database
node_public_cmds -->|"gets translations"| node_localization
node_mod_cmds -->|"gets translations"| node_localization
node_tts_service -->|"reads settings"| node_database
node_tts_service -->|"uses config"| node_settings
node_tts_service -->|"cleans text"| node_text_clean
node_tts_service -.->|"dispatches jobs"| node_worker
node_worker -->|"loads engine"| node_engine
node_worker -->|"loads styles"| node_voice_styles
node_worker -.->|"produces audio"| node_audio
node_audio -.->|"streams to voice"| node_discord
node_discord -.->|"plays speech"| node_server_user

click node_entry "https://github.com/derpeloper/ostinato/blob/main/src/index.js"
click node_events "https://github.com/derpeloper/ostinato/tree/main/src/events"
click node_public_cmds "https://github.com/derpeloper/ostinato/tree/main/src/commands/public"
click node_mod_cmds "https://github.com/derpeloper/ostinato/tree/main/src/commands/mods"
click node_tts_service "https://github.com/derpeloper/ostinato/blob/main/src/services/OstinatoTTS.js"
click node_worker "https://github.com/derpeloper/ostinato/blob/main/src/services/ttsWorker.js"
click node_engine "https://github.com/derpeloper/ostinato/blob/main/src/engine/helper.mjs"
click node_text_clean "https://github.com/derpeloper/ostinato/blob/main/src/utils/cleanText.js"
click node_voice_styles "https://github.com/derpeloper/ostinato/tree/main/src/assets/engine/voice_styles"
click node_settings "https://github.com/derpeloper/ostinato/blob/main/src/config.js"
click node_database "https://github.com/derpeloper/ostinato/blob/main/src/data/db.js"
click node_localization "https://github.com/derpeloper/ostinato/blob/main/src/localization/localize.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_entry,node_events,node_server_user toneBlue
class node_public_cmds,node_mod_cmds toneAmber
class node_tts_service,node_worker,node_engine,node_text_clean,node_voice_styles,node_audio toneMint
class node_settings,node_database,node_localization toneRose
class node_discord toneIndigo
```

## Components

### Discord runtime

- [Bot entry](https://github.com/derpeloper/ostinato/blob/main/src/index.js): `src/index.js`
- [Event handlers](https://github.com/derpeloper/ostinato/tree/main/src/events): `src/events`

### Commands and settings

- [User commands](https://github.com/derpeloper/ostinato/tree/main/src/commands/public): `src/commands/public`
- [Moderator commands](https://github.com/derpeloper/ostinato/tree/main/src/commands/mods): `src/commands/mods`

### Speech pipeline

- [TTS service](https://github.com/derpeloper/ostinato/blob/main/src/services/OstinatoTTS.js): `src/services/OstinatoTTS.js`
- [TTS workers](https://github.com/derpeloper/ostinato/blob/main/src/services/ttsWorker.js): `src/services/ttsWorker.js`
- [Supertonic engine](https://github.com/derpeloper/ostinato/blob/main/src/engine/helper.mjs): `src/engine/helper.mjs`
- [Text cleanup](https://github.com/derpeloper/ostinato/blob/main/src/utils/cleanText.js): `src/utils/cleanText.js`
- [Voice styles](https://github.com/derpeloper/ostinato/tree/main/src/assets/engine/voice_styles): `src/assets/engine/voice_styles`
- **FFmpeg audio**

### Persistence and language

- [Runtime config](https://github.com/derpeloper/ostinato/blob/main/src/config.js): `src/config.js`
- [SQLite settings](https://github.com/derpeloper/ostinato/blob/main/src/data/db.js): `src/data/db.js`
- [Translations](https://github.com/derpeloper/ostinato/blob/main/src/localization/localize.js): `src/localization/localize.js`

### Other components

- **Server user**
- **Discord**

## Connections

- Server user → Discord: sends messages (evidence: `README.md`)
- Discord → Bot entry: delivers events (evidence: `README.md`)
- Bot entry → Event handlers: loads handlers (evidence: `src/index.js`)
- Bot entry → TTS service: initializes (evidence: `src/index.js`)
- Bot entry → User commands: loads commands
- Bot entry → Moderator commands: loads commands
- Event handlers → TTS service: requests speech (evidence: `src/events/tts.js`)
- User commands → SQLite settings: reads/writes (evidence: `src/commands/public/name.js`)
- Moderator commands → SQLite settings: reads/writes (evidence: `src/commands/mods/message.js`)
- User commands → Translations: gets translations (evidence: `src/commands/public/name.js`)
- Moderator commands → Translations: gets translations (evidence: `src/commands/mods/message.js`)
- TTS service → SQLite settings: reads settings (evidence: `src/services/OstinatoTTS.js`)
- TTS service → Runtime config: uses config (evidence: `src/services/OstinatoTTS.js`)
- TTS service → Text cleanup: cleans text (evidence: `src/services/OstinatoTTS.js`)
- TTS service → TTS workers: dispatches jobs (evidence: `README.md`)
- TTS workers → Supertonic engine: loads engine (evidence: `src/services/ttsWorker.js`)
- TTS workers → Voice styles: loads styles (evidence: `src/services/ttsWorker.js`)
- TTS workers → FFmpeg audio: produces audio (evidence: `README.md`)
- FFmpeg audio → Discord: streams to voice (evidence: `README.md`)
- Discord → Server user: plays speech (evidence: `README.md`)