# zachorosz/byom architecture

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

- Interactive diagram: https://gitdiagram.com/zachorosz/byom
- Repository: https://github.com/zachorosz/byom
- Video tour (about a minute): https://gitdiagram.com/zachorosz/byom/video

## Overview

byom is a proof-of-concept music-library manager. A user adds a filesystem location and starts a scan; the scanner walks and synchronizes it into SQLite, then signals a background parse pipeline that extracts audio tags and images and imports browsable albums, tracks, and artists. The UI exposes library browsing, album versions, location management, and scan status/history through RPC, with image blobs served separately. The README documents the scan/parse stages; wiring details for unsampled RPC, importer, and storage implementations are represented only where the tree and sampled entry points support them.

Main entry points: [`scan/scanner.go`](https://github.com/zachorosz/byom/blob/main/scan/scanner.go) (Scan coordinator), [`metadata/pipeline.go`](https://github.com/zachorosz/byom/blob/main/metadata/pipeline.go) (Parse pipeline), [`ui/src/lib/rpc/client.ts`](https://github.com/zachorosz/byom/blob/main/ui/src/lib/rpc/client.ts) (RPC client), [`sqlite/sqlite.go`](https://github.com/zachorosz/byom/blob/main/sqlite/sqlite.go) (SQLite stores)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["Web interface"]
  node_web["App shell<br/>[App.tsx]"]
  node_library_pages["Library pages<br/>[index.tsx]"]
  node_album_detail["Album details<br/>[&#91;id&#93;.tsx]"]
  node_artist_pages["Artist pages<br/>[index.tsx]"]
  node_management_pages["Management pages<br/>[settings.tsx]"]
  node_rpc_client["RPC client<br/>[client.ts]"]
end

subgraph group_api["RPC services"]
  node_library_rpc["Library RPC<br/>[library.go]"]
  node_management_rpc["Management RPC<br/>[management.go]"]
  node_rpc_server["RPC handler<br/>[rpc.go]"]
  node_image_handler["Image endpoint<br/>[handler.go]"]
end

subgraph group_ingest["Library ingestion"]
  node_scanner["Scan coordinator<br/>[scanner.go]"]
  node_walker["Filesystem walker<br/>[walk.go]"]
  node_sync["Directory sync<br/>[sync.go]"]
  node_pipeline["Parse pipeline<br/>[pipeline.go]"]
  node_parser["Metadata parser<br/>[parser.go]"]
  node_importer["Library importer<br/>[importer.go]"]
  node_audio_reader["Audio metadata<br/>[reader.go]"]
end

subgraph group_data["Persistence and media"]
  node_sqlite[("SQLite stores<br/>[sqlite.go]")]
  node_location_store[("Location storage<br/>[location.go]")]
  node_image_store[("Image store<br/>[store.go]")]
end

node_user(("Library user"))
node_filesystem[("Music filesystem")]

node_user -->|"browses and manages"| node_web
node_web -->|"routes to"| node_library_pages
node_web -->|"routes to"| node_management_pages
node_library_pages -->|"requests library data"| node_rpc_client
node_artist_pages -->|"requests artist data"| node_rpc_client
node_album_detail -->|"requests album data"| node_rpc_client
node_management_pages -->|"manages locations and scans"| node_rpc_client
node_rpc_client -->|"sends RPC"| node_rpc_server
node_rpc_server -->|"dispatches library calls"| node_library_rpc
node_rpc_server -->|"dispatches management calls"| node_management_rpc
node_library_rpc -->|"reads library"| node_sqlite
node_management_rpc -->|"starts and monitors scans"| node_scanner
node_management_rpc -->|"manages locations"| node_location_store
node_scanner -->|"resolves scan root"| node_location_store
node_scanner -->|"walks location"| node_walker
node_walker -->|"reads directories"| node_filesystem
node_scanner -->|"syncs walk results"| node_sync
node_sync -->|"updates scan state"| node_sqlite
node_scanner -->|"records and sweeps scans"| node_sqlite
node_scanner -->|"signals dirty dirs"| node_pipeline
node_pipeline -->|"claims dirs and reads files"| node_sqlite
node_pipeline -->|"resolves location"| node_location_store
node_pipeline -->|"parses claimed dir"| node_parser
node_parser -->|"reads audio and images"| node_filesystem
node_parser -->|"extracts audio tags"| node_audio_reader
node_parser -->|"stores image blobs"| node_image_store
node_pipeline -->|"hands over parse result"| node_importer
node_importer -->|"imports library records"| node_sqlite
node_image_handler -->|"opens image blobs"| node_image_store
node_user -->|"requests cover image"| node_image_handler

click node_web "https://github.com/zachorosz/byom/blob/main/ui/src/App.tsx"
click node_library_pages "https://github.com/zachorosz/byom/blob/main/ui/src/routes/albums/index.tsx"
click node_album_detail "https://github.com/zachorosz/byom/blob/main/ui/src/routes/albums/%5Bid%5D.tsx"
click node_artist_pages "https://github.com/zachorosz/byom/blob/main/ui/src/routes/artists/index.tsx"
click node_management_pages "https://github.com/zachorosz/byom/blob/main/ui/src/routes/settings.tsx"
click node_rpc_client "https://github.com/zachorosz/byom/blob/main/ui/src/lib/rpc/client.ts"
click node_library_rpc "https://github.com/zachorosz/byom/blob/main/rpc/library.go"
click node_management_rpc "https://github.com/zachorosz/byom/blob/main/rpc/management.go"
click node_rpc_server "https://github.com/zachorosz/byom/blob/main/rpc/rpc.go"
click node_scanner "https://github.com/zachorosz/byom/blob/main/scan/scanner.go"
click node_walker "https://github.com/zachorosz/byom/blob/main/scan/walk.go"
click node_sync "https://github.com/zachorosz/byom/blob/main/scan/sync.go"
click node_pipeline "https://github.com/zachorosz/byom/blob/main/metadata/pipeline.go"
click node_parser "https://github.com/zachorosz/byom/blob/main/metadata/parser.go"
click node_importer "https://github.com/zachorosz/byom/blob/main/metadata/importer.go"
click node_audio_reader "https://github.com/zachorosz/byom/blob/main/metadata/reader.go"
click node_sqlite "https://github.com/zachorosz/byom/blob/main/sqlite/sqlite.go"
click node_location_store "https://github.com/zachorosz/byom/blob/main/sqlite/location.go"
click node_image_store "https://github.com/zachorosz/byom/blob/main/images/store.go"
click node_image_handler "https://github.com/zachorosz/byom/blob/main/images/handler.go"

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_web,node_library_pages,node_album_detail,node_artist_pages,node_management_pages,node_rpc_client,node_user toneBlue
class node_library_rpc,node_management_rpc,node_rpc_server,node_image_handler,node_filesystem toneAmber
class node_scanner,node_walker,node_sync,node_pipeline,node_parser,node_importer,node_audio_reader toneMint
class node_sqlite,node_location_store,node_image_store toneRose
```

## Components

### Web interface

- [App shell](https://github.com/zachorosz/byom/blob/main/ui/src/App.tsx): `ui/src/App.tsx`
- [Library pages](https://github.com/zachorosz/byom/blob/main/ui/src/routes/albums/index.tsx): `ui/src/routes/albums/index.tsx`
- [Album details](https://github.com/zachorosz/byom/blob/main/ui/src/routes/albums/%5Bid%5D.tsx): `ui/src/routes/albums/[id].tsx`
- [Artist pages](https://github.com/zachorosz/byom/blob/main/ui/src/routes/artists/index.tsx): `ui/src/routes/artists/index.tsx`
- [Management pages](https://github.com/zachorosz/byom/blob/main/ui/src/routes/settings.tsx): `ui/src/routes/settings.tsx`
- [RPC client](https://github.com/zachorosz/byom/blob/main/ui/src/lib/rpc/client.ts): `ui/src/lib/rpc/client.ts`

### RPC services

- [Library RPC](https://github.com/zachorosz/byom/blob/main/rpc/library.go): `rpc/library.go`
- [Management RPC](https://github.com/zachorosz/byom/blob/main/rpc/management.go): `rpc/management.go`
- [RPC handler](https://github.com/zachorosz/byom/blob/main/rpc/rpc.go): `rpc/rpc.go`
- [Image endpoint](https://github.com/zachorosz/byom/blob/main/images/handler.go): `images/handler.go`

### Library ingestion

- [Scan coordinator](https://github.com/zachorosz/byom/blob/main/scan/scanner.go): `scan/scanner.go`
- [Filesystem walker](https://github.com/zachorosz/byom/blob/main/scan/walk.go): `scan/walk.go`
- [Directory sync](https://github.com/zachorosz/byom/blob/main/scan/sync.go): `scan/sync.go`
- [Parse pipeline](https://github.com/zachorosz/byom/blob/main/metadata/pipeline.go): `metadata/pipeline.go`
- [Metadata parser](https://github.com/zachorosz/byom/blob/main/metadata/parser.go): `metadata/parser.go`
- [Library importer](https://github.com/zachorosz/byom/blob/main/metadata/importer.go): `metadata/importer.go`
- [Audio metadata](https://github.com/zachorosz/byom/blob/main/metadata/reader.go): `metadata/reader.go`

### Persistence and media

- [SQLite stores](https://github.com/zachorosz/byom/blob/main/sqlite/sqlite.go): `sqlite/sqlite.go`
- [Location storage](https://github.com/zachorosz/byom/blob/main/sqlite/location.go): `sqlite/location.go`
- [Image store](https://github.com/zachorosz/byom/blob/main/images/store.go): `images/store.go`

### Other components

- **Library user**
- **Music filesystem**

## Connections

- Library user → App shell: browses and manages
- App shell → Library pages: routes to
- App shell → Management pages: routes to
- Library pages → RPC client: requests library data
- Artist pages → RPC client: requests artist data
- Album details → RPC client: requests album data
- Management pages → RPC client: manages locations and scans
- RPC client → RPC handler: sends RPC
- RPC handler → Library RPC: dispatches library calls
- RPC handler → Management RPC: dispatches management calls
- Library RPC → SQLite stores: reads library
- Management RPC → Scan coordinator: starts and monitors scans
- Management RPC → Location storage: manages locations
- Scan coordinator → Location storage: resolves scan root
- Scan coordinator → Filesystem walker: walks location
- Filesystem walker → Music filesystem: reads directories
- Scan coordinator → Directory sync: syncs walk results
- Directory sync → SQLite stores: updates scan state
- Scan coordinator → SQLite stores: records and sweeps scans
- Scan coordinator → Parse pipeline: signals dirty dirs
- Parse pipeline → SQLite stores: claims dirs and reads files
- Parse pipeline → Location storage: resolves location
- Parse pipeline → Metadata parser: parses claimed dir
- Metadata parser → Music filesystem: reads audio and images
- Metadata parser → Audio metadata: extracts audio tags
- Metadata parser → Image store: stores image blobs
- Parse pipeline → Library importer: hands over parse result
- Library importer → SQLite stores: imports library records
- Image endpoint → Image store: opens image blobs
- Library user → Image endpoint: requests cover image