# shithawk/jacobsmusic architecture

> Architecture diagram of the GitHub repository shithawk/jacobsmusic, 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/shithawk/jacobsmusic
- Repository: https://github.com/shithawk/jacobsmusic

## Overview

Jacob’s Music is a personal, installable music PWA. A user opens the web app, browses or adds music, and plays tracks; downloaded music and app state can be kept on-device. The app also supports YouTube and SoundCloud streaming, while Caddy serves it locally or over Tailscale/LAN. Catalog generation and offline shell caching are additional capabilities. The app’s implementation is largely concentrated in one file; relationships below are limited to the shown excerpts and README, so unsampled wiring is omitted.

Main entry points: [`web/app.js`](https://github.com/shithawk/jacobsmusic/blob/main/web/app.js) (Music interface), [`Caddyfile`](https://github.com/shithawk/jacobsmusic/blob/main/Caddyfile) (Caddy server), [`web/sw.js`](https://github.com/shithawk/jacobsmusic/blob/main/web/sw.js) (Offline shell)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["Music app"]
  node_music_app["Music interface<br/>[app.js]"]
  node_track_browse["Track browsing<br/>[app.js]"]
  node_track_playback["Track playback<br/>[app.js]"]
  node_device_library["Device library<br/>[app.js]"]
  node_artist_browse["Artist browsing<br/>[app.js]"]
  node_browser_storage[("IndexedDB")]
end

subgraph group_media["Media sources"]
  node_youtube_add["YouTube tracks<br/>[app.js]"]
  node_soundcloud["SoundCloud streaming<br/>[app.js]"]
  node_music_files[("Music files")]
  node_catalog["YouTube catalog<br/>[catalog.json]"]
end

subgraph group_delivery["Delivery"]
  node_offline_shell["Offline shell<br/>[sw.js]"]
  node_caddy["Caddy server"]
end

node_listener(("Listener"))
node_user_device(("User device"))

node_listener -->|"uses"| node_music_app
node_music_app -->|"renders"| node_track_browse
node_music_app -->|"renders"| node_artist_browse
node_music_app -->|"selects tracks"| node_track_playback
node_music_app -->|"adds videos"| node_youtube_add
node_track_playback -.->|"plays tracks"| node_soundcloud
node_track_playback -.->|"plays tracks"| node_youtube_add
node_music_app -->|"fetches downloads"| node_music_files
node_music_app -->|"writes tracks and files"| node_browser_storage
node_music_app -->|"downloads tracks"| node_device_library
node_caddy -->|"serves locally"| node_music_app
node_user_device -->|"connects"| node_caddy
node_offline_shell -->|"caches app shell"| node_user_device

click node_music_app "https://github.com/shithawk/jacobsmusic/blob/main/web/app.js"
click node_track_browse "https://github.com/shithawk/jacobsmusic/blob/main/web/app.js"
click node_track_playback "https://github.com/shithawk/jacobsmusic/blob/main/web/app.js"
click node_device_library "https://github.com/shithawk/jacobsmusic/blob/main/web/app.js"
click node_artist_browse "https://github.com/shithawk/jacobsmusic/blob/main/web/app.js"
click node_youtube_add "https://github.com/shithawk/jacobsmusic/blob/main/web/app.js"
click node_soundcloud "https://github.com/shithawk/jacobsmusic/blob/main/web/app.js"
click node_catalog "https://github.com/shithawk/jacobsmusic/blob/main/youtube/catalog.json"
click node_offline_shell "https://github.com/shithawk/jacobsmusic/blob/main/web/sw.js"
click node_caddy "https://github.com/shithawk/jacobsmusic/blob/main/Caddyfile"

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_music_app,node_track_browse,node_track_playback,node_device_library,node_artist_browse,node_browser_storage,node_user_device toneBlue
class node_youtube_add,node_soundcloud,node_music_files,node_catalog toneAmber
class node_offline_shell,node_caddy toneMint
class node_listener toneIndigo
```

## Components

### Music app

- [Music interface](https://github.com/shithawk/jacobsmusic/blob/main/web/app.js): `web/app.js`
- [Track browsing](https://github.com/shithawk/jacobsmusic/blob/main/web/app.js): `web/app.js`
- [Track playback](https://github.com/shithawk/jacobsmusic/blob/main/web/app.js): `web/app.js`
- [Device library](https://github.com/shithawk/jacobsmusic/blob/main/web/app.js): `web/app.js`
- [Artist browsing](https://github.com/shithawk/jacobsmusic/blob/main/web/app.js): `web/app.js`
- **IndexedDB**

### Media sources

- [YouTube tracks](https://github.com/shithawk/jacobsmusic/blob/main/web/app.js): `web/app.js`
- [SoundCloud streaming](https://github.com/shithawk/jacobsmusic/blob/main/web/app.js): `web/app.js`
- **Music files**
- [YouTube catalog](https://github.com/shithawk/jacobsmusic/blob/main/youtube/catalog.json): `youtube/catalog.json`

### Delivery

- [Offline shell](https://github.com/shithawk/jacobsmusic/blob/main/web/sw.js): `web/sw.js`
- [Caddy server](https://github.com/shithawk/jacobsmusic/blob/main/Caddyfile): `Caddyfile`

### Other components

- **Listener**
- **User device**

## Connections

- Listener → Music interface: uses (evidence: `README.md`)
- Music interface → Track browsing: renders (evidence: `web/app.js`)
- Music interface → Artist browsing: renders (evidence: `web/app.js`)
- Music interface → Track playback: selects tracks (evidence: `web/app.js`)
- Music interface → YouTube tracks: adds videos (evidence: `web/app.js`)
- Track playback → SoundCloud streaming: plays tracks (evidence: `web/app.js`)
- Track playback → YouTube tracks: plays tracks (evidence: `web/app.js`)
- Music interface → Music files: fetches downloads (evidence: `web/app.js`)
- Music interface → IndexedDB: writes tracks and files (evidence: `web/app.js`)
- Music interface → Device library: downloads tracks (evidence: `web/app.js`)
- Caddy server → Music interface: serves locally (evidence: `README.md`)
- User device → Caddy server: connects (evidence: `README.md`)
- Offline shell → User device: caches app shell (evidence: `web/sw.js`)
