# oceansofgamesspc-crypto/bozos-tts-beta architecture

> Architecture diagram of the GitHub repository oceansofgamesspc-crypto/bozos-tts-beta, 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/oceansofgamesspc-crypto/bozos-tts-beta
- Repository: https://github.com/oceansofgamesspc-crypto/bozos-tts-beta

## Overview

This is a sharded Discord text-to-speech bot, with an additional opt-in, spatial-audio conversation-portal feature. Users interact through Discord commands and voice channels; the bot selects a voice, produces speech, and plays audio, while portal sessions relay microphone and TTS audio between guilds. The excerpts establish the shard launcher, main bot, spatial engine, and runtime patches. Since README content is absent and index.js is only sampled, finer command-to-subsystem wiring is shown only where the excerpts support it.

Main entry points: [`index.js`](https://github.com/oceansofgamesspc-crypto/bozos-tts-beta/blob/main/index.js) (Bot commands and state), [`shards.js`](https://github.com/oceansofgamesspc-crypto/bozos-tts-beta/blob/main/shards.js) (Shard manager), [`spatialPortalEngine.js`](https://github.com/oceansofgamesspc-crypto/bozos-tts-beta/blob/main/spatialPortalEngine.js) (Portal mixer), [`portalRuntimeFixes.js`](https://github.com/oceansofgamesspc-crypto/bozos-tts-beta/blob/main/portalRuntimeFixes.js) (Portal runtime fixes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Bot runtime"]
  node_shards["Shard manager<br/>[shards.js]"]
  node_bot["Bot commands and state<br/>[index.js]"]
end

subgraph group_tts["Speech and audio"]
  node_voice_catalog["Voice catalog<br/>[index.js]"]
  node_voice_session["Guild voice session<br/>[index.js]"]
  node_spatial["Spatial audio engine"]
end

subgraph group_portal["Conversation portals"]
  node_portal_flow["Portal lifecycle<br/>[index.js]"]
  node_portal_mixer["Portal mixer"]
  node_portal_transport["Portal UDP transport"]
  node_countdown["Portal code countdown"]
  node_portal_fixes["Portal runtime fixes"]
end

subgraph group_ops["Runtime operations"]
  node_health["Health endpoint<br/>[shards.js]"]
end

node_discord_user(("Discord user"))
node_discord(("Discord platform"))
node_edge_tts(("Edge TTS"))
node_monitor(("Health monitor"))

node_discord_user -->|"issues commands"| node_discord
node_discord -->|"delivers interactions"| node_bot
node_bot -->|"selects voice"| node_voice_catalog
node_bot -->|"manages playback"| node_voice_session
node_bot -->|"assigns positions"| node_spatial
node_bot -->|"handles portal actions"| node_portal_flow
node_shards -->|"spawns shards"| node_bot
node_shards -->|"loads patch"| node_countdown
node_shards -->|"loads patch"| node_portal_fixes
node_portal_fixes -->|"patches runtime"| node_portal_mixer
node_portal_flow -->|"sends portal controls"| node_discord
node_portal_mixer -->|"plays mixed audio"| node_discord
node_monitor -->|"requests status"| node_health
node_health -->|"collects shard stats"| node_shards
node_edge_tts -.->|"provides speech audio"| node_voice_session

click node_shards "https://github.com/oceansofgamesspc-crypto/bozos-tts-beta/blob/main/shards.js"
click node_bot "https://github.com/oceansofgamesspc-crypto/bozos-tts-beta/blob/main/index.js"
click node_voice_catalog "https://github.com/oceansofgamesspc-crypto/bozos-tts-beta/blob/main/index.js"
click node_voice_session "https://github.com/oceansofgamesspc-crypto/bozos-tts-beta/blob/main/index.js"
click node_spatial "https://github.com/oceansofgamesspc-crypto/bozos-tts-beta/blob/main/spatialPortalEngine.js"
click node_portal_flow "https://github.com/oceansofgamesspc-crypto/bozos-tts-beta/blob/main/index.js"
click node_portal_mixer "https://github.com/oceansofgamesspc-crypto/bozos-tts-beta/blob/main/spatialPortalEngine.js"
click node_portal_transport "https://github.com/oceansofgamesspc-crypto/bozos-tts-beta/blob/main/spatialPortalEngine.js"
click node_countdown "https://github.com/oceansofgamesspc-crypto/bozos-tts-beta/blob/main/portalCountdownPatch.js"
click node_portal_fixes "https://github.com/oceansofgamesspc-crypto/bozos-tts-beta/blob/main/portalRuntimeFixes.js"
click node_health "https://github.com/oceansofgamesspc-crypto/bozos-tts-beta/blob/main/shards.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_shards,node_bot,node_discord_user toneBlue
class node_voice_catalog,node_voice_session,node_spatial toneAmber
class node_portal_flow,node_portal_mixer,node_portal_transport,node_countdown,node_portal_fixes toneMint
class node_health toneRose
class node_discord,node_edge_tts,node_monitor toneIndigo
```

## Components

### Bot runtime

- [Shard manager](https://github.com/oceansofgamesspc-crypto/bozos-tts-beta/blob/main/shards.js): `shards.js`
- [Bot commands and state](https://github.com/oceansofgamesspc-crypto/bozos-tts-beta/blob/main/index.js): `index.js`

### Speech and audio

- [Voice catalog](https://github.com/oceansofgamesspc-crypto/bozos-tts-beta/blob/main/index.js): `index.js`
- [Guild voice session](https://github.com/oceansofgamesspc-crypto/bozos-tts-beta/blob/main/index.js): `index.js`
- [Spatial audio engine](https://github.com/oceansofgamesspc-crypto/bozos-tts-beta/blob/main/spatialPortalEngine.js): `spatialPortalEngine.js`

### Conversation portals

- [Portal lifecycle](https://github.com/oceansofgamesspc-crypto/bozos-tts-beta/blob/main/index.js): `index.js`
- [Portal mixer](https://github.com/oceansofgamesspc-crypto/bozos-tts-beta/blob/main/spatialPortalEngine.js): `spatialPortalEngine.js`
- [Portal UDP transport](https://github.com/oceansofgamesspc-crypto/bozos-tts-beta/blob/main/spatialPortalEngine.js): `spatialPortalEngine.js`
- [Portal code countdown](https://github.com/oceansofgamesspc-crypto/bozos-tts-beta/blob/main/portalCountdownPatch.js): `portalCountdownPatch.js`
- [Portal runtime fixes](https://github.com/oceansofgamesspc-crypto/bozos-tts-beta/blob/main/portalRuntimeFixes.js): `portalRuntimeFixes.js`

### Runtime operations

- [Health endpoint](https://github.com/oceansofgamesspc-crypto/bozos-tts-beta/blob/main/shards.js): `shards.js`

### Other components

- **Discord user**
- **Discord platform**
- **Edge TTS**
- **Health monitor**

## Connections

- Discord user → Discord platform: issues commands
- Discord platform → Bot commands and state: delivers interactions
- Bot commands and state → Voice catalog: selects voice
- Bot commands and state → Guild voice session: manages playback
- Bot commands and state → Spatial audio engine: assigns positions
- Bot commands and state → Portal lifecycle: handles portal actions
- Shard manager → Bot commands and state: spawns shards
- Shard manager → Portal code countdown: loads patch
- Shard manager → Portal runtime fixes: loads patch
- Portal runtime fixes → Portal mixer: patches runtime
- Portal lifecycle → Discord platform: sends portal controls
- Portal mixer → Discord platform: plays mixed audio
- Health monitor → Health endpoint: requests status
- Health endpoint → Shard manager: collects shard stats
- Edge TTS → Guild voice session: provides speech audio