# thirteen-labs/deep-player architecture

> Architecture diagram of the GitHub repository thirteen-labs/deep-player, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-22). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/thirteen-labs/deep-player
- Repository: https://github.com/thirteen-labs/deep-player

## Overview

Deep Player is a local-first media player: users scan device media into a local library, browse music and video collections, then play, organize, and cache items for offline use. The app’s Expo Router screens invoke library and playback services; SQLite and Zustand hold library and player state. README documents playlists, favorites, history, queue controls, video playback, permissions, and offline caching. Some subsystem paths are directories because their individual implementation files were not sampled; their links are documented capabilities, not inspected calls.

Main entry points: [`src/app/music.tsx`](https://github.com/thirteen-labs/deep-player/blob/main/src/app/music.tsx) (Music browsing), [`src/app`](https://github.com/thirteen-labs/deep-player/tree/main/src/app) (App routes), [`src/lib/db/store.ts`](https://github.com/thirteen-labs/deep-player/blob/main/src/lib/db/store.ts) (Library operations), [`src/stores/player-store.ts`](https://github.com/thirteen-labs/deep-player/blob/main/src/stores/player-store.ts) (Player state and queue)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["App experience"]
  node_routes["App routes"]
  node_music["Music browsing<br/>[music.tsx]"]
  node_video["Video browsing"]
  node_artists["Artist and album views"]
  node_folders["Folders and home<br/>[folders.tsx]"]
  node_user["User settings<br/>[user.tsx]"]
  node_trackrow["Track rows<br/>[track-row.tsx]"]
end

subgraph group_library["Library and organization"]
  node_scanner["Library scanner<br/>[scan.ts]"]
  node_metadata["Metadata reader<br/>[metadata.ts]"]
  node_dbstore["Library operations<br/>[store.ts]"]
  node_sqlite[("SQLite database<br/>[schema.ts]")]
  node_sorting["Track sorting<br/>[track-sorting.ts]"]
  node_playlists["Playlists and favorites<br/>[store.ts]"]
  node_cache["Offline cache<br/>[cache.ts]"]
end

subgraph group_playback["Playback"]
  node_playerui["Now playing controls"]
  node_playerstate["Player state and queue<br/>[player-store.ts]"]
  node_engine["Audio engine<br/>[player.ts]"]
  node_videoengine["Video playback"]
end

subgraph group_platform["Local services and settings"]
  node_permissions["Media permissions<br/>[permissions.ts]"]
  node_theme["Themes<br/>[theme.ts]"]
end

node_listener(("Listener"))

node_listener -->|"uses"| node_routes
node_routes -->|"routes to"| node_music
node_routes -->|"routes to"| node_video
node_routes -->|"routes to"| node_artists
node_routes -->|"routes to"| node_folders
node_routes -->|"routes to"| node_user
node_music -->|"scans library"| node_scanner
node_music -->|"reads tags"| node_metadata
node_music -->|"browses tracks"| node_dbstore
node_artists -->|"browses tracks"| node_dbstore
node_video -->|"browses videos"| node_dbstore
node_scanner -->|"imports assets"| node_sqlite
node_dbstore -->|"reads and writes"| node_sqlite
node_playlists -->|"persists collections"| node_sqlite
node_music -->|"manages tracks"| node_playlists
node_music -->|"sorts tracks"| node_sorting
node_music -->|"renders tracks"| node_trackrow
node_trackrow -.->|"offers playback actions"| node_playerstate
node_playerui -->|"controls"| node_playerstate
node_playerstate -->|"controls audio"| node_engine
node_playerstate -->|"persists playback"| node_dbstore
node_playerstate -->|"updates queue"| node_playlists
node_video -.->|"plays videos"| node_videoengine
node_music -->|"warms offline cache"| node_cache
node_cache -->|"stores local URIs"| node_dbstore
node_user -->|"manages access"| node_permissions
node_user -.->|"selects theme"| node_theme

click node_routes "https://github.com/thirteen-labs/deep-player/tree/main/src/app"
click node_music "https://github.com/thirteen-labs/deep-player/blob/main/src/app/music.tsx"
click node_video "https://github.com/thirteen-labs/deep-player/tree/main/src/app/videos"
click node_artists "https://github.com/thirteen-labs/deep-player/tree/main/src/app/artists"
click node_folders "https://github.com/thirteen-labs/deep-player/blob/main/src/app/folders.tsx"
click node_user "https://github.com/thirteen-labs/deep-player/blob/main/src/app/user.tsx"
click node_trackrow "https://github.com/thirteen-labs/deep-player/blob/main/src/components/ui/track-row.tsx"
click node_scanner "https://github.com/thirteen-labs/deep-player/blob/main/src/lib/library/scan.ts"
click node_metadata "https://github.com/thirteen-labs/deep-player/blob/main/src/lib/metadata.ts"
click node_dbstore "https://github.com/thirteen-labs/deep-player/blob/main/src/lib/db/store.ts"
click node_sqlite "https://github.com/thirteen-labs/deep-player/blob/main/src/lib/db/schema.ts"
click node_sorting "https://github.com/thirteen-labs/deep-player/blob/main/src/utils/track-sorting.ts"
click node_playlists "https://github.com/thirteen-labs/deep-player/blob/main/src/lib/db/store.ts"
click node_cache "https://github.com/thirteen-labs/deep-player/blob/main/src/lib/library/cache.ts"
click node_playerui "https://github.com/thirteen-labs/deep-player/blob/main/src/components/ui/now-playing-card.tsx"
click node_playerstate "https://github.com/thirteen-labs/deep-player/blob/main/src/stores/player-store.ts"
click node_engine "https://github.com/thirteen-labs/deep-player/blob/main/src/lib/audio/player.ts"
click node_videoengine "https://github.com/thirteen-labs/deep-player/tree/main/src/app/videos"
click node_permissions "https://github.com/thirteen-labs/deep-player/blob/main/src/lib/permissions.ts"
click node_theme "https://github.com/thirteen-labs/deep-player/blob/main/src/constants/theme.ts"

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_routes,node_music,node_video,node_artists,node_folders,node_user,node_trackrow toneBlue
class node_scanner,node_metadata,node_dbstore,node_sqlite,node_sorting,node_playlists,node_cache toneAmber
class node_playerui,node_playerstate,node_engine,node_videoengine toneMint
class node_permissions,node_theme toneRose
class node_listener toneIndigo
```

## Components

### App experience

- [App routes](https://github.com/thirteen-labs/deep-player/tree/main/src/app): `src/app`
- [Music browsing](https://github.com/thirteen-labs/deep-player/blob/main/src/app/music.tsx): `src/app/music.tsx`
- [Video browsing](https://github.com/thirteen-labs/deep-player/tree/main/src/app/videos): `src/app/videos`
- [Artist and album views](https://github.com/thirteen-labs/deep-player/tree/main/src/app/artists): `src/app/artists`
- [Folders and home](https://github.com/thirteen-labs/deep-player/blob/main/src/app/folders.tsx): `src/app/folders.tsx`
- [User settings](https://github.com/thirteen-labs/deep-player/blob/main/src/app/user.tsx): `src/app/user.tsx`
- [Track rows](https://github.com/thirteen-labs/deep-player/blob/main/src/components/ui/track-row.tsx): `src/components/ui/track-row.tsx`

### Library and organization

- [Library scanner](https://github.com/thirteen-labs/deep-player/blob/main/src/lib/library/scan.ts): `src/lib/library/scan.ts`
- [Metadata reader](https://github.com/thirteen-labs/deep-player/blob/main/src/lib/metadata.ts): `src/lib/metadata.ts`
- [Library operations](https://github.com/thirteen-labs/deep-player/blob/main/src/lib/db/store.ts): `src/lib/db/store.ts`
- [SQLite database](https://github.com/thirteen-labs/deep-player/blob/main/src/lib/db/schema.ts): `src/lib/db/schema.ts`
- [Track sorting](https://github.com/thirteen-labs/deep-player/blob/main/src/utils/track-sorting.ts): `src/utils/track-sorting.ts`
- [Playlists and favorites](https://github.com/thirteen-labs/deep-player/blob/main/src/lib/db/store.ts): `src/lib/db/store.ts`
- [Offline cache](https://github.com/thirteen-labs/deep-player/blob/main/src/lib/library/cache.ts): `src/lib/library/cache.ts`

### Playback

- [Now playing controls](https://github.com/thirteen-labs/deep-player/blob/main/src/components/ui/now-playing-card.tsx): `src/components/ui/now-playing-card.tsx`
- [Player state and queue](https://github.com/thirteen-labs/deep-player/blob/main/src/stores/player-store.ts): `src/stores/player-store.ts`
- [Audio engine](https://github.com/thirteen-labs/deep-player/blob/main/src/lib/audio/player.ts): `src/lib/audio/player.ts`
- [Video playback](https://github.com/thirteen-labs/deep-player/tree/main/src/app/videos): `src/app/videos`

### Local services and settings

- [Media permissions](https://github.com/thirteen-labs/deep-player/blob/main/src/lib/permissions.ts): `src/lib/permissions.ts`
- [Themes](https://github.com/thirteen-labs/deep-player/blob/main/src/constants/theme.ts): `src/constants/theme.ts`

### Other components

- **Listener**

## Connections

- Listener → App routes: uses (evidence: `README.md`)
- App routes → Music browsing: routes to (evidence: `README.md`)
- App routes → Video browsing: routes to (evidence: `README.md`)
- App routes → Artist and album views: routes to (evidence: `README.md`)
- App routes → Folders and home: routes to (evidence: `README.md`)
- App routes → User settings: routes to (evidence: `README.md`)
- Music browsing → Library scanner: scans library (evidence: `src/app/music.tsx`)
- Music browsing → Metadata reader: reads tags (evidence: `src/app/music.tsx`)
- Music browsing → Library operations: browses tracks (evidence: `src/app/music.tsx`)
- Artist and album views → Library operations: browses tracks (evidence: `src/app/artists/[name].tsx`)
- Video browsing → Library operations: browses videos (evidence: `src/app/videos/index.tsx`)
- Library scanner → SQLite database: imports assets (evidence: `README.md`)
- Library operations → SQLite database: reads and writes (evidence: `src/lib/db/store.ts`)
- Playlists and favorites → SQLite database: persists collections (evidence: `README.md`)
- Music browsing → Playlists and favorites: manages tracks (evidence: `README.md`)
- Music browsing → Track sorting: sorts tracks (evidence: `src/app/music.tsx`)
- Music browsing → Track rows: renders tracks (evidence: `src/app/music.tsx`)
- Track rows → Player state and queue: offers playback actions
- Now playing controls → Player state and queue: controls (evidence: `src/components/ui/now-playing-card.tsx`)
- Player state and queue → Audio engine: controls audio (evidence: `src/stores/player-store.ts`)
- Player state and queue → Library operations: persists playback (evidence: `src/stores/player-store.ts`)
- Player state and queue → Playlists and favorites: updates queue (evidence: `README.md`)
- Video browsing → Video playback: plays videos (evidence: `README.md`)
- Music browsing → Offline cache: warms offline cache
- Offline cache → Library operations: stores local URIs (evidence: `src/lib/library/cache.ts`)
- User settings → Media permissions: manages access (evidence: `README.md`)
- User settings → Themes: selects theme (evidence: `README.md`)
