# brandon-james-dev/web-media-manager architecture

> Architecture diagram of the GitHub repository brandon-james-dev/web-media-manager, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/brandon-james-dev/web-media-manager
- Repository: https://github.com/brandon-james-dev/web-media-manager

## Overview

Web Media Manager is a browser-based music library manager and player. Its main user flow is to add or scan a music source, browse and edit the resulting library, manage playlists, and play tracks; optional branches include device synchronization and offline caching. The application also provides theme and visualizer extensions, lyrics tools, and background jobs. The graph combines README-documented capabilities with bootstrap and extension-manager relationships visible in excerpts; several domain implementations were not sampled, so their internal call paths are not asserted.

Main entry points: [`src/App.tsx`](https://github.com/brandon-james-dev/web-media-manager/blob/master/src/App.tsx) (App shell), [`src/core/visualizers/PluginManager.ts`](https://github.com/brandon-james-dev/web-media-manager/blob/master/src/core/visualizers/PluginManager.ts) (Visualizer plugins), [`src/lib/background-jobs/BackgroundService.ts`](https://github.com/brandon-james-dev/web-media-manager/blob/master/src/lib/background-jobs/BackgroundService.ts) (Background jobs), [`src/core/themes/ThemeManager.ts`](https://github.com/brandon-james-dev/web-media-manager/blob/master/src/core/themes/ThemeManager.ts) (Theme management)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["Application"]
  node_app["App shell<br/>[App.tsx]"]
  node_ui["Shared UI primitives<br/>[button.tsx]"]
  node_events["Event dispatch<br/>[index.ts]"]
  node_localization["Localization<br/>[resources.ts]"]
  node_toast["Notifications UI<br/>[toast.tsx]"]
end

subgraph group_library["Library and Sources"]
  node_songs["Library browsing"]
  node_source["Music sources"]
  node_scan["Library scanning"]
  node_metadata["Metadata editing"]
  node_playlists["Playlists"]
  node_tracklist["Theme track list<br/>[trackColumns.ts]"]
end

subgraph group_playback["Playback and Lyrics"]
  node_playback["Playback engine"]
  node_lyrics["Lyrics tools"]
end

subgraph group_devices["Devices and Jobs"]
  node_sync["Device synchronization"]
  node_offline["Offline downloads"]
  node_jobs["Background jobs"]
  node_jobevents["Job events"]
  node_jobnotifications["Job notifications"]
end

subgraph group_extensions["Themes and Extensions"]
  node_themes["Theme management<br/>[ThemeManager.ts]"]
  node_themehooks["Theme hooks<br/>[useThemes.ts]"]
  node_themeports["Theme store port<br/>[themes.ts]"]
  node_visualizers["Visualizer plugins<br/>[PluginManager.ts]"]
  node_pluginsettings["Plugin settings<br/>[settings.ts]"]
  node_pluginvalidation["Manifest validation"]
  node_packagefiles["Package file port<br/>[packageFiles.ts]"]
end

node_user(("Listener / Manager"))

node_user -->|"uses"| node_app
node_app -->|"browses"| node_songs
node_app -->|"adds source"| node_source
node_source -->|"scans library"| node_scan
node_app -->|"edits metadata"| node_metadata
node_app -->|"manages playlists"| node_playlists
node_app -->|"provides playback"| node_playback
node_app -->|"provides sync"| node_sync
node_app -->|"selects theme"| node_themes
node_songs -.->|"displays tracks"| node_tracklist
node_playback -.->|"shows lyrics"| node_lyrics
node_app -->|"caches audio"| node_offline
node_sync -->|"runs sync jobs"| node_jobs
node_offline -->|"runs downloads"| node_jobs
node_jobs -->|"publishes progress"| node_jobevents
node_jobevents -.->|"drives notices"| node_jobnotifications
node_jobnotifications -.->|"shows notices"| node_toast
node_app -->|"manages plugins"| node_visualizers
node_visualizers -->|"uses settings"| node_pluginsettings
node_visualizers -->|"validates manifests"| node_pluginvalidation
node_visualizers -->|"stores package files"| node_packagefiles
node_app -->|"loads themes"| node_themehooks
node_themehooks -->|"calls manager"| node_themes
node_themes -->|"reads and writes"| node_themeports
node_app -->|"connects dispatch"| node_events

click node_app "https://github.com/brandon-james-dev/web-media-manager/blob/master/src/App.tsx"
click node_songs "https://github.com/brandon-james-dev/web-media-manager/tree/master/src/core/browsing"
click node_source "https://github.com/brandon-james-dev/web-media-manager/tree/master/src/lib/sources"
click node_scan "https://github.com/brandon-james-dev/web-media-manager/tree/master/src/core/scanning"
click node_metadata "https://github.com/brandon-james-dev/web-media-manager/tree/master/src/core/metadata"
click node_playlists "https://github.com/brandon-james-dev/web-media-manager/tree/master/src/core/playlists"
click node_tracklist "https://github.com/brandon-james-dev/web-media-manager/blob/master/src/components/theme-widgets/library/TrackList/trackColumns.ts"
click node_ui "https://github.com/brandon-james-dev/web-media-manager/blob/master/src/components/ui/button.tsx"
click node_playback "https://github.com/brandon-james-dev/web-media-manager/blob/master/src/providers/PlaybackProvider.tsx"
click node_lyrics "https://github.com/brandon-james-dev/web-media-manager/tree/master/src/lib/lyrics-providers"
click node_sync "https://github.com/brandon-james-dev/web-media-manager/tree/master/src/lib/sync"
click node_offline "https://github.com/brandon-james-dev/web-media-manager/tree/master/src/lib/offline"
click node_jobs "https://github.com/brandon-james-dev/web-media-manager/blob/master/src/lib/background-jobs/BackgroundService.ts"
click node_jobevents "https://github.com/brandon-james-dev/web-media-manager/blob/master/src/events/background-job-events.ts"
click node_jobnotifications "https://github.com/brandon-james-dev/web-media-manager/blob/master/src/events/job-notifications.ts"
click node_themes "https://github.com/brandon-james-dev/web-media-manager/blob/master/src/core/themes/ThemeManager.ts"
click node_themehooks "https://github.com/brandon-james-dev/web-media-manager/blob/master/src/hooks/useThemes.ts"
click node_themeports "https://github.com/brandon-james-dev/web-media-manager/blob/master/src/core/ports/themes.ts"
click node_visualizers "https://github.com/brandon-james-dev/web-media-manager/blob/master/src/core/visualizers/PluginManager.ts"
click node_pluginsettings "https://github.com/brandon-james-dev/web-media-manager/blob/master/src/core/visualizers/manifest/settings.ts"
click node_pluginvalidation "https://github.com/brandon-james-dev/web-media-manager/blob/master/src/core/visualizers/manifest/validateManifest.ts"
click node_packagefiles "https://github.com/brandon-james-dev/web-media-manager/blob/master/src/core/ports/packageFiles.ts"
click node_events "https://github.com/brandon-james-dev/web-media-manager/blob/master/src/events/index.ts"
click node_localization "https://github.com/brandon-james-dev/web-media-manager/blob/master/src/i18n/resources.ts"
click node_toast "https://github.com/brandon-james-dev/web-media-manager/blob/master/src/components/ui/toast.tsx"

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,node_ui,node_events,node_localization,node_toast toneBlue
class node_songs,node_source,node_scan,node_metadata,node_playlists,node_tracklist toneAmber
class node_playback,node_lyrics toneMint
class node_sync,node_offline,node_jobs,node_jobevents,node_jobnotifications toneRose
class node_themes,node_themehooks,node_themeports,node_visualizers,node_pluginsettings,node_pluginvalidation,node_packagefiles,node_user toneIndigo
```

## Components

### Application

- [App shell](https://github.com/brandon-james-dev/web-media-manager/blob/master/src/App.tsx): `src/App.tsx`
- [Shared UI primitives](https://github.com/brandon-james-dev/web-media-manager/blob/master/src/components/ui/button.tsx): `src/components/ui/button.tsx`
- [Event dispatch](https://github.com/brandon-james-dev/web-media-manager/blob/master/src/events/index.ts): `src/events/index.ts`
- [Localization](https://github.com/brandon-james-dev/web-media-manager/blob/master/src/i18n/resources.ts): `src/i18n/resources.ts`
- [Notifications UI](https://github.com/brandon-james-dev/web-media-manager/blob/master/src/components/ui/toast.tsx): `src/components/ui/toast.tsx`

### Library and Sources

- [Library browsing](https://github.com/brandon-james-dev/web-media-manager/tree/master/src/core/browsing): `src/core/browsing`
- [Music sources](https://github.com/brandon-james-dev/web-media-manager/tree/master/src/lib/sources): `src/lib/sources`
- [Library scanning](https://github.com/brandon-james-dev/web-media-manager/tree/master/src/core/scanning): `src/core/scanning`
- [Metadata editing](https://github.com/brandon-james-dev/web-media-manager/tree/master/src/core/metadata): `src/core/metadata`
- [Playlists](https://github.com/brandon-james-dev/web-media-manager/tree/master/src/core/playlists): `src/core/playlists`
- [Theme track list](https://github.com/brandon-james-dev/web-media-manager/blob/master/src/components/theme-widgets/library/TrackList/trackColumns.ts): `src/components/theme-widgets/library/TrackList/trackColumns.ts`

### Playback and Lyrics

- [Playback engine](https://github.com/brandon-james-dev/web-media-manager/blob/master/src/providers/PlaybackProvider.tsx): `src/providers/PlaybackProvider.tsx`
- [Lyrics tools](https://github.com/brandon-james-dev/web-media-manager/tree/master/src/lib/lyrics-providers): `src/lib/lyrics-providers`

### Devices and Jobs

- [Device synchronization](https://github.com/brandon-james-dev/web-media-manager/tree/master/src/lib/sync): `src/lib/sync`
- [Offline downloads](https://github.com/brandon-james-dev/web-media-manager/tree/master/src/lib/offline): `src/lib/offline`
- [Background jobs](https://github.com/brandon-james-dev/web-media-manager/blob/master/src/lib/background-jobs/BackgroundService.ts): `src/lib/background-jobs/BackgroundService.ts`
- [Job events](https://github.com/brandon-james-dev/web-media-manager/blob/master/src/events/background-job-events.ts): `src/events/background-job-events.ts`
- [Job notifications](https://github.com/brandon-james-dev/web-media-manager/blob/master/src/events/job-notifications.ts): `src/events/job-notifications.ts`

### Themes and Extensions

- [Theme management](https://github.com/brandon-james-dev/web-media-manager/blob/master/src/core/themes/ThemeManager.ts): `src/core/themes/ThemeManager.ts`
- [Theme hooks](https://github.com/brandon-james-dev/web-media-manager/blob/master/src/hooks/useThemes.ts): `src/hooks/useThemes.ts`
- [Theme store port](https://github.com/brandon-james-dev/web-media-manager/blob/master/src/core/ports/themes.ts): `src/core/ports/themes.ts`
- [Visualizer plugins](https://github.com/brandon-james-dev/web-media-manager/blob/master/src/core/visualizers/PluginManager.ts): `src/core/visualizers/PluginManager.ts`
- [Plugin settings](https://github.com/brandon-james-dev/web-media-manager/blob/master/src/core/visualizers/manifest/settings.ts): `src/core/visualizers/manifest/settings.ts`
- [Manifest validation](https://github.com/brandon-james-dev/web-media-manager/blob/master/src/core/visualizers/manifest/validateManifest.ts): `src/core/visualizers/manifest/validateManifest.ts`
- [Package file port](https://github.com/brandon-james-dev/web-media-manager/blob/master/src/core/ports/packageFiles.ts): `src/core/ports/packageFiles.ts`

### Other components

- **Listener / Manager**

## Connections

- Listener / Manager → App shell: uses (evidence: `README.md`)
- App shell → Library browsing: browses (evidence: `README.md`)
- App shell → Music sources: adds source (evidence: `README.md`)
- Music sources → Library scanning: scans library (evidence: `README.md`)
- App shell → Metadata editing: edits metadata (evidence: `README.md`)
- App shell → Playlists: manages playlists (evidence: `README.md`)
- App shell → Playback engine: provides playback (evidence: `src/App.tsx`)
- App shell → Device synchronization: provides sync (evidence: `src/App.tsx`)
- App shell → Theme management: selects theme (evidence: `src/App.tsx`)
- Library browsing → Theme track list: displays tracks
- Playback engine → Lyrics tools: shows lyrics
- App shell → Offline downloads: caches audio (evidence: `README.md`)
- Device synchronization → Background jobs: runs sync jobs (evidence: `README.md`)
- Offline downloads → Background jobs: runs downloads (evidence: `README.md`)
- Background jobs → Job events: publishes progress (evidence: `src/lib/background-jobs/BackgroundService.ts`)
- Job events → Job notifications: drives notices
- Job notifications → Notifications UI: shows notices
- App shell → Visualizer plugins: manages plugins
- Visualizer plugins → Plugin settings: uses settings (evidence: `src/core/visualizers/PluginManager.ts`)
- Visualizer plugins → Manifest validation: validates manifests (evidence: `src/core/visualizers/PluginManager.ts`)
- Visualizer plugins → Package file port: stores package files (evidence: `src/core/visualizers/PluginManager.ts`)
- App shell → Theme hooks: loads themes (evidence: `src/App.tsx`)
- Theme hooks → Theme management: calls manager (evidence: `src/hooks/useThemes.ts`)
- Theme management → Theme store port: reads and writes (evidence: `src/core/themes/ThemeManager.ts`)
- App shell → Event dispatch: connects dispatch (evidence: `src/App.tsx`)
