# m4ndril/ioke architecture

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

- Interactive diagram: https://gitdiagram.com/m4ndril/ioke
- Repository: https://github.com/m4ndril/ioke

## Overview

IOkê is a local-first karaoke application: users add songs, the PC prepares tracks and lyrics, and the player presents a timed sing-along. For parties, phones join a queue and control the TV stage. The graph preserves documented add-on, package, key/MIDI, and cloud-separation capabilities. Several backend and frontend modules were not sampled; those subsystems are represented at their exact tree paths, with relationships included only where supported by the README or excerpts.

Main entry points: [`karaoke/library.py`](https://github.com/m4ndril/ioke/blob/main/karaoke/library.py) (Song library and queue), [`server.py`](https://github.com/m4ndril/ioke/blob/main/server.py) (HTTP server), [`web/js/player.js`](https://github.com/m4ndril/ioke/blob/main/web/js/player.js) (Karaoke player), [`karaoke/nuvem/separador_nuvem.py`](https://github.com/m4ndril/ioke/blob/main/karaoke/nuvem/separador_nuvem.py) (Cloud separation jobs)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["App and library"]
  node_server["HTTP server<br/>[server.py]"]
  node_library[("Song library and queue<br/>[library.py]")]
  node_database[("App database<br/>[db.py]")]
end

subgraph group_prep["Song preparation"]
  node_prep_media["Media and metadata<br/>[midia.py]"]
  node_lyrics["Lyrics and alignment<br/>[aligner.py]"]
  node_artwork["Cover artwork<br/>[artwork.py]"]
  node_separation["Vocal separation<br/>[separation.py]"]
end

subgraph group_play["Playback and party"]
  node_player["Karaoke player<br/>[player.js]"]
  node_party["Party queue and scoring<br/>[party.py]"]
  node_stage["TV stage<br/>[stage.py]"]
  node_accounts[("Phone accounts<br/>[accounts.py]")]
  node_mobile["Phone interface<br/>[mobile.js]"]
  node_key_midi["Key and MIDI<br/>[transpose.py]"]
end

subgraph group_extensions["Extensions and exchange"]
  node_addons["Add-on management<br/>[__init__.py]"]
  node_addon_api["Add-on routes<br/>[api.py]"]
  node_packages["Karaoke packages<br/>[pacotes.py]"]
end

subgraph group_platform["Cloud and settings"]
  node_cloud_work["Cloud separation jobs<br/>[separador_nuvem.py]"]
  node_cloud_account["Cloud account and costs<br/>[conta.py]"]
  node_settings["Settings and language<br/>[config.py]"]
end

node_pc_user(("PC user"))
node_phone_users(("Phone users"))
node_song_files["Local song files"]
node_external_cloud{{"Modal cloud"}}

node_pc_user -->|"adds songs"| node_server
node_song_files -->|"ingests files"| node_library
node_server -->|"queues and manages"| node_library
node_library -.->|"prepares media"| node_prep_media
node_library -->|"aligns lyrics"| node_lyrics
node_library -->|"gets cover"| node_artwork
node_library -.->|"separates vocals"| node_separation
node_cloud_work -->|"uses credentials"| node_cloud_account
node_cloud_work -->|"submits jobs"| node_external_cloud
node_library -.->|"uses cloud option"| node_cloud_work
node_pc_user -->|"selects a song"| node_player
node_player -->|"requests song data"| node_server
node_player -->|"changes key"| node_key_midi
node_pc_user -->|"opens TV stage"| node_stage
node_phone_users -->|"joins party"| node_mobile
node_mobile -.->|"uses phone APIs"| node_server
node_server -->|"registers account routes"| node_accounts
node_server -.->|"serves party actions"| node_party
node_stage -.->|"shows party state"| node_party
node_pc_user -->|"installs add-ons"| node_addons
node_server -.->|"serves add-on routes"| node_addon_api
node_addons -.->|"exposes add-on API"| node_addon_api
node_pc_user -->|"exchanges packages"| node_packages
node_library -.->|"persists song state"| node_database
node_server -->|"reads configuration"| node_settings

click node_server "https://github.com/m4ndril/ioke/blob/main/server.py"
click node_library "https://github.com/m4ndril/ioke/blob/main/karaoke/library.py"
click node_database "https://github.com/m4ndril/ioke/blob/main/karaoke/db.py"
click node_prep_media "https://github.com/m4ndril/ioke/blob/main/karaoke/midia.py"
click node_lyrics "https://github.com/m4ndril/ioke/blob/main/karaoke/aligner.py"
click node_artwork "https://github.com/m4ndril/ioke/blob/main/karaoke/artwork.py"
click node_separation "https://github.com/m4ndril/ioke/blob/main/karaoke/separation.py"
click node_cloud_work "https://github.com/m4ndril/ioke/blob/main/karaoke/nuvem/separador_nuvem.py"
click node_cloud_account "https://github.com/m4ndril/ioke/blob/main/karaoke/nuvem/conta.py"
click node_player "https://github.com/m4ndril/ioke/blob/main/web/js/player.js"
click node_party "https://github.com/m4ndril/ioke/blob/main/karaoke/party.py"
click node_stage "https://github.com/m4ndril/ioke/blob/main/karaoke/stage.py"
click node_accounts "https://github.com/m4ndril/ioke/blob/main/karaoke/accounts.py"
click node_mobile "https://github.com/m4ndril/ioke/blob/main/web/js/mobile.js"
click node_addons "https://github.com/m4ndril/ioke/blob/main/karaoke/complementos/__init__.py"
click node_addon_api "https://github.com/m4ndril/ioke/blob/main/karaoke/complementos/api.py"
click node_packages "https://github.com/m4ndril/ioke/blob/main/karaoke/pacotes.py"
click node_key_midi "https://github.com/m4ndril/ioke/blob/main/karaoke/transpose.py"
click node_settings "https://github.com/m4ndril/ioke/blob/main/karaoke/config.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_server,node_library,node_database,node_pc_user,node_phone_users toneBlue
class node_prep_media,node_lyrics,node_artwork,node_separation toneAmber
class node_player,node_party,node_stage,node_accounts,node_mobile,node_key_midi toneMint
class node_addons,node_addon_api,node_packages toneRose
class node_cloud_work,node_cloud_account,node_settings,node_song_files,node_external_cloud toneIndigo
```

## Components

### App and library

- [HTTP server](https://github.com/m4ndril/ioke/blob/main/server.py): `server.py`
- [Song library and queue](https://github.com/m4ndril/ioke/blob/main/karaoke/library.py): `karaoke/library.py`
- [App database](https://github.com/m4ndril/ioke/blob/main/karaoke/db.py): `karaoke/db.py`

### Song preparation

- [Media and metadata](https://github.com/m4ndril/ioke/blob/main/karaoke/midia.py): `karaoke/midia.py`
- [Lyrics and alignment](https://github.com/m4ndril/ioke/blob/main/karaoke/aligner.py): `karaoke/aligner.py`
- [Cover artwork](https://github.com/m4ndril/ioke/blob/main/karaoke/artwork.py): `karaoke/artwork.py`
- [Vocal separation](https://github.com/m4ndril/ioke/blob/main/karaoke/separation.py): `karaoke/separation.py`

### Playback and party

- [Karaoke player](https://github.com/m4ndril/ioke/blob/main/web/js/player.js): `web/js/player.js`
- [Party queue and scoring](https://github.com/m4ndril/ioke/blob/main/karaoke/party.py): `karaoke/party.py`
- [TV stage](https://github.com/m4ndril/ioke/blob/main/karaoke/stage.py): `karaoke/stage.py`
- [Phone accounts](https://github.com/m4ndril/ioke/blob/main/karaoke/accounts.py): `karaoke/accounts.py`
- [Phone interface](https://github.com/m4ndril/ioke/blob/main/web/js/mobile.js): `web/js/mobile.js`
- [Key and MIDI](https://github.com/m4ndril/ioke/blob/main/karaoke/transpose.py): `karaoke/transpose.py`

### Extensions and exchange

- [Add-on management](https://github.com/m4ndril/ioke/blob/main/karaoke/complementos/__init__.py): `karaoke/complementos/__init__.py`
- [Add-on routes](https://github.com/m4ndril/ioke/blob/main/karaoke/complementos/api.py): `karaoke/complementos/api.py`
- [Karaoke packages](https://github.com/m4ndril/ioke/blob/main/karaoke/pacotes.py): `karaoke/pacotes.py`

### Cloud and settings

- [Cloud separation jobs](https://github.com/m4ndril/ioke/blob/main/karaoke/nuvem/separador_nuvem.py): `karaoke/nuvem/separador_nuvem.py`
- [Cloud account and costs](https://github.com/m4ndril/ioke/blob/main/karaoke/nuvem/conta.py): `karaoke/nuvem/conta.py`
- [Settings and language](https://github.com/m4ndril/ioke/blob/main/karaoke/config.py): `karaoke/config.py`

### Other components

- **PC user**
- **Phone users**
- **Local song files**
- **Modal cloud**

## Connections

- PC user → HTTP server: adds songs (evidence: `README.md`)
- Local song files → Song library and queue: ingests files (evidence: `README.md`)
- HTTP server → Song library and queue: queues and manages (evidence: `server.py`)
- Song library and queue → Media and metadata: prepares media (evidence: `karaoke/library.py`)
- Song library and queue → Lyrics and alignment: aligns lyrics (evidence: `karaoke/library.py`)
- Song library and queue → Cover artwork: gets cover (evidence: `karaoke/library.py`)
- Song library and queue → Vocal separation: separates vocals (evidence: `karaoke/library.py`)
- Cloud separation jobs → Cloud account and costs: uses credentials (evidence: `karaoke/nuvem/separador_nuvem.py`)
- Cloud separation jobs → Modal cloud: submits jobs (evidence: `karaoke/nuvem/separador_nuvem.py`)
- Song library and queue → Cloud separation jobs: uses cloud option (evidence: `karaoke/library.py`)
- PC user → Karaoke player: selects a song (evidence: `README.md`)
- Karaoke player → HTTP server: requests song data (evidence: `web/js/player.js`)
- Karaoke player → Key and MIDI: changes key (evidence: `README.md`)
- PC user → TV stage: opens TV stage (evidence: `README.md`)
- Phone users → Phone interface: joins party (evidence: `README.md`)
- Phone interface → HTTP server: uses phone APIs
- HTTP server → Phone accounts: registers account routes (evidence: `server.py`)
- HTTP server → Party queue and scoring: serves party actions (evidence: `server.py`)
- TV stage → Party queue and scoring: shows party state
- PC user → Add-on management: installs add-ons (evidence: `README.md`)
- HTTP server → Add-on routes: serves add-on routes (evidence: `server.py`)
- Add-on management → Add-on routes: exposes add-on API
- PC user → Karaoke packages: exchanges packages (evidence: `README.md`)
- Song library and queue → App database: persists song state
- HTTP server → Settings and language: reads configuration (evidence: `server.py`)
