# cyttorak-j/oli architecture

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

- Interactive diagram: https://gitdiagram.com/cyttorak-j/oli
- Repository: https://github.com/cyttorak-j/oli

## Overview

Oli is a local-first music player and library manager, with desktop Windows/macOS and an Android alpha client. The main workflow is browsing or searching local and online music, then playing it or downloading it; library scanning, metadata, saved playback state, and playlists support the local collection. The graph also preserves the documented Internet Archive, YouTube, and Android capabilities. Source detail is uneven: some edges come from README statements or SOURCE INDEX references, so unsampled implementation relationships are not expanded.

Main entry points: [`src/main/ipc.ts`](https://github.com/cyttorak-j/oli/blob/main/src/main/ipc.ts) (IPC handlers), [`src/main/index.ts`](https://github.com/cyttorak-j/oli/blob/main/src/main/index.ts) (Electron startup), [`src/main/services/database.ts`](https://github.com/cyttorak-j/oli/blob/main/src/main/services/database.ts) (Library database), [`src/main/services/search.ts`](https://github.com/cyttorak-j/oli/blob/main/src/main/services/search.ts) (Search service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_desktop_ui["Desktop experience"]
  node_app_ui["App navigation<br/>[App.tsx]"]
  node_search_ui["Search page<br/>[Search.tsx]"]
  node_player_ui["Player state<br/>[player.ts]"]
  node_ipc_ui["Renderer IPC<br/>[ipc.ts]"]
end

subgraph group_desktop_core["Desktop services"]
  node_main["Electron startup<br/>[index.ts]"]
  node_ipc_main["IPC handlers<br/>[ipc.ts]"]
  node_library["Library scan<br/>[library.ts]"]
  node_search["Search service<br/>[search.ts]"]
  node_providers["Online providers<br/>[provider.ts]"]
  node_downloads["Downloads<br/>[downloads.ts]"]
  node_archive["Archive access<br/>[archive.ts]"]
  node_ytdlp["YouTube engine<br/>[ytdlpEngine.ts]"]
  node_metadata["Metadata tools<br/>[metadataOps.ts]"]
  node_playlists["Playlists<br/>[playlists.ts]"]
  node_playback["Playback state<br/>[playerState.ts]"]
  node_database[("Library database<br/>[database.ts]")]
end

subgraph group_android["Android client"]
  node_android_activity["Android activity<br/>[MainActivity.java]"]
  node_android_audio["Native audio engine"]
  node_android_audio_service["Background audio"]
  node_android_download_service["Download service"]
  node_android_download["Resumable downloads"]
end

subgraph group_shared["Shared contracts"]
end

node_user(("Listener"))
node_local_music["Local music files"]
node_online["Online catalogs"]

node_user -->|"uses"| node_app_ui
node_app_ui -->|"routes to"| node_search_ui
node_app_ui -->|"resumes playback"| node_player_ui
node_search_ui -->|"requests results"| node_ipc_ui
node_player_ui -->|"calls"| node_ipc_ui
node_ipc_ui -.->|"sends requests"| node_ipc_main
node_main -.->|"registers handlers"| node_ipc_main
node_main -->|"initializes"| node_database
node_main -->|"constructs"| node_search
node_main -->|"constructs"| node_providers
node_main -->|"constructs"| node_downloads
node_main -->|"constructs"| node_playlists
node_main -->|"constructs"| node_playback
node_ipc_main -->|"dispatches requests"| node_library
node_ipc_main -->|"dispatches requests"| node_search
node_ipc_main -->|"dispatches requests"| node_downloads
node_ipc_main -->|"dispatches requests"| node_archive
node_ipc_main -->|"dispatches requests"| node_metadata
node_ipc_main -->|"dispatches requests"| node_playlists
node_ipc_main -->|"dispatches requests"| node_playback
node_search -->|"queries"| node_database
node_search -->|"searches online"| node_providers
node_library -->|"scans"| node_local_music
node_archive -->|"searches and downloads"| node_online
node_ytdlp -->|"enables YouTube"| node_online
node_downloads -->|"downloads media"| node_online
node_android_activity -->|"starts"| node_android_audio_service
node_android_audio_service -->|"controls playback"| node_android_audio
node_android_activity -->|"starts"| node_android_download_service
node_android_download_service -->|"delegates downloads"| node_android_download
node_android_download -.->|"fetches media"| node_online
node_metadata -.->|"updates library"| node_database
node_playlists -->|"persists playlists"| node_database
node_playback -->|"persists state"| node_database

click node_app_ui "https://github.com/cyttorak-j/oli/blob/main/src/renderer/src/App.tsx"
click node_search_ui "https://github.com/cyttorak-j/oli/blob/main/src/renderer/src/pages/Search.tsx"
click node_player_ui "https://github.com/cyttorak-j/oli/blob/main/src/renderer/src/store/player.ts"
click node_ipc_ui "https://github.com/cyttorak-j/oli/blob/main/src/renderer/src/lib/ipc.ts"
click node_main "https://github.com/cyttorak-j/oli/blob/main/src/main/index.ts"
click node_ipc_main "https://github.com/cyttorak-j/oli/blob/main/src/main/ipc.ts"
click node_library "https://github.com/cyttorak-j/oli/blob/main/src/main/services/library.ts"
click node_search "https://github.com/cyttorak-j/oli/blob/main/src/main/services/search.ts"
click node_providers "https://github.com/cyttorak-j/oli/blob/main/src/main/services/provider.ts"
click node_downloads "https://github.com/cyttorak-j/oli/blob/main/src/main/services/downloads.ts"
click node_archive "https://github.com/cyttorak-j/oli/blob/main/src/main/services/archive.ts"
click node_ytdlp "https://github.com/cyttorak-j/oli/blob/main/src/main/services/ytdlpEngine.ts"
click node_metadata "https://github.com/cyttorak-j/oli/blob/main/src/main/services/metadataOps.ts"
click node_playlists "https://github.com/cyttorak-j/oli/blob/main/src/main/services/playlists.ts"
click node_playback "https://github.com/cyttorak-j/oli/blob/main/src/main/services/playerState.ts"
click node_database "https://github.com/cyttorak-j/oli/blob/main/src/main/services/database.ts"
click node_android_activity "https://github.com/cyttorak-j/oli/blob/main/android/app/src/main/java/com/cyttos/oli/MainActivity.java"
click node_android_audio "https://github.com/cyttorak-j/oli/blob/main/android/app/src/main/java/com/cyttos/oli/OliAudioEngine.java"
click node_android_audio_service "https://github.com/cyttorak-j/oli/blob/main/android/app/src/main/java/com/cyttos/oli/OliAudioService.java"
click node_android_download_service "https://github.com/cyttorak-j/oli/blob/main/android/app/src/main/java/com/cyttos/oli/OliDownloadService.java"
click node_android_download "https://github.com/cyttorak-j/oli/blob/main/android/app/src/main/java/com/cyttos/oli/DownloadEngine.java"

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_ui,node_search_ui,node_player_ui,node_ipc_ui toneBlue
class node_main,node_ipc_main,node_library,node_search,node_providers,node_downloads,node_archive,node_ytdlp,node_metadata,node_playlists,node_playback,node_database toneAmber
class node_android_activity,node_android_audio,node_android_audio_service,node_android_download_service,node_android_download toneMint
class node_user,node_local_music,node_online toneIndigo
```

## Components

### Desktop experience

- [App navigation](https://github.com/cyttorak-j/oli/blob/main/src/renderer/src/App.tsx): `src/renderer/src/App.tsx`
- [Search page](https://github.com/cyttorak-j/oli/blob/main/src/renderer/src/pages/Search.tsx): `src/renderer/src/pages/Search.tsx`
- [Player state](https://github.com/cyttorak-j/oli/blob/main/src/renderer/src/store/player.ts): `src/renderer/src/store/player.ts`
- [Renderer IPC](https://github.com/cyttorak-j/oli/blob/main/src/renderer/src/lib/ipc.ts): `src/renderer/src/lib/ipc.ts`

### Desktop services

- [Electron startup](https://github.com/cyttorak-j/oli/blob/main/src/main/index.ts): `src/main/index.ts`
- [IPC handlers](https://github.com/cyttorak-j/oli/blob/main/src/main/ipc.ts): `src/main/ipc.ts`
- [Library scan](https://github.com/cyttorak-j/oli/blob/main/src/main/services/library.ts): `src/main/services/library.ts`
- [Search service](https://github.com/cyttorak-j/oli/blob/main/src/main/services/search.ts): `src/main/services/search.ts`
- [Online providers](https://github.com/cyttorak-j/oli/blob/main/src/main/services/provider.ts): `src/main/services/provider.ts`
- [Downloads](https://github.com/cyttorak-j/oli/blob/main/src/main/services/downloads.ts): `src/main/services/downloads.ts`
- [Archive access](https://github.com/cyttorak-j/oli/blob/main/src/main/services/archive.ts): `src/main/services/archive.ts`
- [YouTube engine](https://github.com/cyttorak-j/oli/blob/main/src/main/services/ytdlpEngine.ts): `src/main/services/ytdlpEngine.ts`
- [Metadata tools](https://github.com/cyttorak-j/oli/blob/main/src/main/services/metadataOps.ts): `src/main/services/metadataOps.ts`
- [Playlists](https://github.com/cyttorak-j/oli/blob/main/src/main/services/playlists.ts): `src/main/services/playlists.ts`
- [Playback state](https://github.com/cyttorak-j/oli/blob/main/src/main/services/playerState.ts): `src/main/services/playerState.ts`
- [Library database](https://github.com/cyttorak-j/oli/blob/main/src/main/services/database.ts): `src/main/services/database.ts`

### Android client

- [Android activity](https://github.com/cyttorak-j/oli/blob/main/android/app/src/main/java/com/cyttos/oli/MainActivity.java): `android/app/src/main/java/com/cyttos/oli/MainActivity.java`
- [Native audio engine](https://github.com/cyttorak-j/oli/blob/main/android/app/src/main/java/com/cyttos/oli/OliAudioEngine.java): `android/app/src/main/java/com/cyttos/oli/OliAudioEngine.java`
- [Background audio](https://github.com/cyttorak-j/oli/blob/main/android/app/src/main/java/com/cyttos/oli/OliAudioService.java): `android/app/src/main/java/com/cyttos/oli/OliAudioService.java`
- [Download service](https://github.com/cyttorak-j/oli/blob/main/android/app/src/main/java/com/cyttos/oli/OliDownloadService.java): `android/app/src/main/java/com/cyttos/oli/OliDownloadService.java`
- [Resumable downloads](https://github.com/cyttorak-j/oli/blob/main/android/app/src/main/java/com/cyttos/oli/DownloadEngine.java): `android/app/src/main/java/com/cyttos/oli/DownloadEngine.java`

### Other components

- **Listener**
- **Local music files**
- **Online catalogs**

## Connections

- Listener → App navigation: uses (evidence: `README.md`)
- App navigation → Search page: routes to (evidence: `src/renderer/src/App.tsx`)
- App navigation → Player state: resumes playback (evidence: `src/renderer/src/App.tsx`)
- Search page → Renderer IPC: requests results (evidence: `src/renderer/src/pages/Search.tsx`)
- Player state → Renderer IPC: calls (evidence: `src/renderer/src/store/player.ts`)
- Renderer IPC → IPC handlers: sends requests
- Electron startup → IPC handlers: registers handlers (evidence: `src/main/index.ts`)
- Electron startup → Library database: initializes (evidence: `src/main/index.ts`)
- Electron startup → Search service: constructs (evidence: `src/main/index.ts`)
- Electron startup → Online providers: constructs (evidence: `src/main/index.ts`)
- Electron startup → Downloads: constructs (evidence: `src/main/index.ts`)
- Electron startup → Playlists: constructs (evidence: `src/main/index.ts`)
- Electron startup → Playback state: constructs (evidence: `src/main/index.ts`)
- IPC handlers → Library scan: dispatches requests (evidence: `src/main/ipc.ts`)
- IPC handlers → Search service: dispatches requests (evidence: `src/main/ipc.ts`)
- IPC handlers → Downloads: dispatches requests (evidence: `src/main/ipc.ts`)
- IPC handlers → Archive access: dispatches requests (evidence: `src/main/ipc.ts`)
- IPC handlers → Metadata tools: dispatches requests (evidence: `src/main/ipc.ts`)
- IPC handlers → Playlists: dispatches requests (evidence: `src/main/ipc.ts`)
- IPC handlers → Playback state: dispatches requests (evidence: `src/main/ipc.ts`)
- Search service → Library database: queries (evidence: `src/main/services/search.ts`)
- Search service → Online providers: searches online (evidence: `src/main/services/search.ts`)
- Library scan → Local music files: scans (evidence: `README.md`)
- Archive access → Online catalogs: searches and downloads (evidence: `README.md`)
- YouTube engine → Online catalogs: enables YouTube (evidence: `README.md`)
- Downloads → Online catalogs: downloads media (evidence: `README.md`)
- Android activity → Background audio: starts (evidence: `android/app/src/main/java/com/cyttos/oli/OliAudioService.java`)
- Background audio → Native audio engine: controls playback (evidence: `android/app/src/main/java/com/cyttos/oli/OliAudioService.java`)
- Android activity → Download service: starts (evidence: `android/app/src/main/java/com/cyttos/oli/OliDownloadService.java`)
- Download service → Resumable downloads: delegates downloads (evidence: `android/app/src/main/java/com/cyttos/oli/OliDownloadService.java`)
- Resumable downloads → Online catalogs: fetches media
- Metadata tools → Library database: updates library
- Playlists → Library database: persists playlists (evidence: `src/main/services/playlists.ts`)
- Playback state → Library database: persists state (evidence: `src/main/services/playerState.ts`)
