# kiseding/koyze architecture

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

- Interactive diagram: https://gitdiagram.com/kiseding/koyze
- Repository: https://github.com/kiseding/koyze

## Overview

Koyze is a cross-platform Flutter music app: users search online and local catalogs, choose playable tracks, manage playback and libraries, and optionally sync account data across devices. Its core music experience is documented as local-first and does not require login or a server. The graph also shows the optional Workers sync service and its playlist-import capability. Flutter implementation files were not included in the supplied tree, so app feature nodes use only the documented enclosing paths; app-internal wiring is limited to the README’s stated data flow.

Main entry points: [`lib/features`](https://github.com/kiseding/koyze/tree/main/lib/features) (Flutter app UI), [`workers/src/index.ts`](https://github.com/kiseding/koyze/blob/main/workers/src/index.ts) (Worker API), [`workers/src/routes/playlist-import.ts`](https://github.com/kiseding/koyze/blob/main/workers/src/routes/playlist-import.ts) (Import route), [`workers/src/db`](https://github.com/kiseding/koyze/tree/main/workers/src/db) (D1 database)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["Music app"]
  node_ui["Flutter app UI"]
  node_search["Search and sources"]
  node_online["Music platforms"]
  node_custom["Custom JS sources"]
  node_import["Playlist import"]
  node_player["Player and queue"]
  node_lyrics["Lyrics"]
end

subgraph group_library["Library and playback"]
  node_local["Local library"]
  node_downloads["Downloads and cache"]
  node_playlists["Playlists and backups"]
  node_stats["Listening stats"]
  node_recommendations["Recommendations"]
end

subgraph group_sync["Optional cloud sync"]
  node_syncclient["Sync client"]
  node_worker["Worker API<br/>[index.ts]"]
  node_auth["Account auth<br/>[auth.ts]"]
  node_syncroute["Sync routes<br/>[sync.ts]"]
  node_eventsroute["Sync event routes<br/>[sync-events.ts]"]
  node_importroute["Import route<br/>[playlist-import.ts]"]
  node_sourceadapters["Import adapters"]
  node_d1[("D1 database")]
  node_kv[("KV cache<br/>[sync-events.ts]")]
  node_rate["Rate limiter"]
end

subgraph group_platform["Platform integrations"]
  node_audio["Audio services"]
  node_device["Device files and controls"]
end

node_listener(("Listener"))
node_cloudplatforms["QQ, Kuwo, NetEase"]

node_listener -->|"uses"| node_ui
node_ui -->|"requests search"| node_search
node_search -->|"searches"| node_online
node_search -->|"searches"| node_local
node_search -.->|"queries enabled source"| node_custom
node_ui -->|"controls playback"| node_player
node_player -->|"plays through"| node_audio
node_player -->|"uses cache"| node_downloads
node_player -->|"loads lyrics"| node_lyrics
node_ui -->|"manages library"| node_local
node_device -->|"provides audio files"| node_local
node_ui -->|"manages downloads"| node_downloads
node_downloads -->|"adds completed tracks"| node_local
node_ui -->|"manages playlists"| node_playlists
node_ui -->|"views statistics"| node_stats
node_stats -->|"informs preferences"| node_recommendations
node_recommendations -->|"finds recommendations"| node_online
node_ui -->|"configures sync"| node_syncclient
node_syncclient -.->|"sends sync requests"| node_worker
node_worker -->|"dispatches auth"| node_auth
node_worker -->|"dispatches sync"| node_syncroute
node_worker -->|"dispatches events"| node_eventsroute
node_worker -->|"dispatches imports"| node_importroute
node_auth -->|"reads and writes users"| node_d1
node_syncroute -->|"reads and writes sync data"| node_d1
node_eventsroute -->|"stores events"| node_d1
node_eventsroute -->|"stores state"| node_kv
node_importroute -->|"searches and imports"| node_sourceadapters
node_sourceadapters -->|"fetches playlists"| node_cloudplatforms
node_importroute -->|"saves playlist"| node_d1
node_importroute -->|"checks limits"| node_rate

click node_ui "https://github.com/kiseding/koyze/tree/main/lib/features"
click node_search "https://github.com/kiseding/koyze/tree/main/lib/features"
click node_custom "https://github.com/kiseding/koyze/tree/main/lib/features"
click node_import "https://github.com/kiseding/koyze/tree/main/lib/features"
click node_player "https://github.com/kiseding/koyze/tree/main/lib/features"
click node_lyrics "https://github.com/kiseding/koyze/tree/main/lib/features"
click node_local "https://github.com/kiseding/koyze/tree/main/lib/features"
click node_downloads "https://github.com/kiseding/koyze/tree/main/lib/features"
click node_playlists "https://github.com/kiseding/koyze/tree/main/lib/features"
click node_stats "https://github.com/kiseding/koyze/tree/main/lib/features"
click node_recommendations "https://github.com/kiseding/koyze/tree/main/lib/features"
click node_syncclient "https://github.com/kiseding/koyze/tree/main/lib/features"
click node_worker "https://github.com/kiseding/koyze/blob/main/workers/src/index.ts"
click node_auth "https://github.com/kiseding/koyze/blob/main/workers/src/routes/user/auth.ts"
click node_syncroute "https://github.com/kiseding/koyze/blob/main/workers/src/routes/user/sync.ts"
click node_eventsroute "https://github.com/kiseding/koyze/blob/main/workers/src/routes/user/sync-events.ts"
click node_importroute "https://github.com/kiseding/koyze/blob/main/workers/src/routes/playlist-import.ts"
click node_sourceadapters "https://github.com/kiseding/koyze/tree/main/workers/src/sources"
click node_d1 "https://github.com/kiseding/koyze/tree/main/workers/src/db"
click node_kv "https://github.com/kiseding/koyze/blob/main/workers/src/db/sync-events.ts"
click node_rate "https://github.com/kiseding/koyze/tree/main/workers/src/middleware"

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_ui,node_search,node_online,node_custom,node_import,node_player,node_lyrics toneBlue
class node_local,node_downloads,node_playlists,node_stats,node_recommendations toneAmber
class node_syncclient,node_worker,node_auth,node_syncroute,node_eventsroute,node_importroute,node_sourceadapters,node_d1,node_kv,node_rate toneMint
class node_audio,node_device toneRose
class node_listener,node_cloudplatforms toneIndigo
```

## Components

### Music app

- [Flutter app UI](https://github.com/kiseding/koyze/tree/main/lib/features): `lib/features`
- [Search and sources](https://github.com/kiseding/koyze/tree/main/lib/features): `lib/features`
- **Music platforms**
- [Custom JS sources](https://github.com/kiseding/koyze/tree/main/lib/features): `lib/features`
- [Playlist import](https://github.com/kiseding/koyze/tree/main/lib/features): `lib/features`
- [Player and queue](https://github.com/kiseding/koyze/tree/main/lib/features): `lib/features`
- [Lyrics](https://github.com/kiseding/koyze/tree/main/lib/features): `lib/features`

### Library and playback

- [Local library](https://github.com/kiseding/koyze/tree/main/lib/features): `lib/features`
- [Downloads and cache](https://github.com/kiseding/koyze/tree/main/lib/features): `lib/features`
- [Playlists and backups](https://github.com/kiseding/koyze/tree/main/lib/features): `lib/features`
- [Listening stats](https://github.com/kiseding/koyze/tree/main/lib/features): `lib/features`
- [Recommendations](https://github.com/kiseding/koyze/tree/main/lib/features): `lib/features`

### Optional cloud sync

- [Sync client](https://github.com/kiseding/koyze/tree/main/lib/features): `lib/features`
- [Worker API](https://github.com/kiseding/koyze/blob/main/workers/src/index.ts): `workers/src/index.ts`
- [Account auth](https://github.com/kiseding/koyze/blob/main/workers/src/routes/user/auth.ts): `workers/src/routes/user/auth.ts`
- [Sync routes](https://github.com/kiseding/koyze/blob/main/workers/src/routes/user/sync.ts): `workers/src/routes/user/sync.ts`
- [Sync event routes](https://github.com/kiseding/koyze/blob/main/workers/src/routes/user/sync-events.ts): `workers/src/routes/user/sync-events.ts`
- [Import route](https://github.com/kiseding/koyze/blob/main/workers/src/routes/playlist-import.ts): `workers/src/routes/playlist-import.ts`
- [Import adapters](https://github.com/kiseding/koyze/tree/main/workers/src/sources): `workers/src/sources`
- [D1 database](https://github.com/kiseding/koyze/tree/main/workers/src/db): `workers/src/db`
- [KV cache](https://github.com/kiseding/koyze/blob/main/workers/src/db/sync-events.ts): `workers/src/db/sync-events.ts`
- [Rate limiter](https://github.com/kiseding/koyze/tree/main/workers/src/middleware): `workers/src/middleware`

### Platform integrations

- **Audio services**
- **Device files and controls**

### Other components

- **Listener**
- **QQ, Kuwo, NetEase**

## Connections

- Listener → Flutter app UI: uses
- Flutter app UI → Search and sources: requests search
- Search and sources → Music platforms: searches
- Search and sources → Local library: searches
- Search and sources → Custom JS sources: queries enabled source
- Flutter app UI → Player and queue: controls playback
- Player and queue → Audio services: plays through
- Player and queue → Downloads and cache: uses cache
- Player and queue → Lyrics: loads lyrics
- Flutter app UI → Local library: manages library
- Device files and controls → Local library: provides audio files
- Flutter app UI → Downloads and cache: manages downloads
- Downloads and cache → Local library: adds completed tracks
- Flutter app UI → Playlists and backups: manages playlists
- Flutter app UI → Listening stats: views statistics
- Listening stats → Recommendations: informs preferences
- Recommendations → Music platforms: finds recommendations
- Flutter app UI → Sync client: configures sync
- Sync client → Worker API: sends sync requests
- Worker API → Account auth: dispatches auth
- Worker API → Sync routes: dispatches sync
- Worker API → Sync event routes: dispatches events
- Worker API → Import route: dispatches imports
- Account auth → D1 database: reads and writes users
- Sync routes → D1 database: reads and writes sync data
- Sync event routes → D1 database: stores events
- Sync event routes → KV cache: stores state
- Import route → Import adapters: searches and imports
- Import adapters → QQ, Kuwo, NetEase: fetches playlists
- Import route → D1 database: saves playlist
- Import route → Rate limiter: checks limits