# karaagexc/akb48-archive architecture

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

- Interactive diagram: https://gitdiagram.com/karaagexc/akb48-archive
- Repository: https://github.com/karaagexc/akb48-archive

## Overview

AKB48 Archive is a self-hosted media library whose main workflow is browsing the hub, finding a title or track, and playing it in the browser. The Express server supplies library metadata, media and supporting assets; the SPA coordinates views and playback. Separate branches cover music and podcast metadata, concert-song recognition, wiki content, TV access, and the Windows launcher. The README documents capabilities beyond the sampled excerpts, so those subsystem links reflect documentation rather than inspected call sites.

Main entry points: [`app/web-app/public/js/spa.js`](https://github.com/karaagexc/akb48-archive/blob/main/app/web-app/public/js/spa.js) (SPA controller), [`app/web-app/server.js`](https://github.com/karaagexc/akb48-archive/blob/main/app/web-app/server.js) (Library API), [`tv-app/wrapper.js`](https://github.com/karaagexc/akb48-archive/blob/main/tv-app/wrapper.js) (TV server picker), [`app/web-app/public/js/hub.js`](https://github.com/karaagexc/akb48-archive/blob/main/app/web-app/public/js/hub.js) (Hub and browse)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web experience"]
  node_spa["SPA controller<br/>[spa.js]"]
  node_hub["Hub and browse<br/>[hub.js]"]
  node_listen["Music view<br/>[listen.js]"]
  node_podcast["Podcast view<br/>[podcast.js]"]
  node_cinema["Video player<br/>[video-player.js]"]
  node_tvmode["TV navigation<br/>[tv.js]"]
end

subgraph group_backend["Archive backend"]
  node_server["Express server<br/>[server.js]"]
  node_library["Library API<br/>[server.js]"]
  node_watch["Watch progress<br/>[server.js]"]
  node_wiki["Wiki proxy<br/>[server.js]"]
  node_mediafiles["Media library"]
  node_presence["Discord presence<br/>[server.js]"]
end

subgraph group_media["Media features"]
  node_musicmeta["Music metadata<br/>[music-metadata.js]"]
  node_podmeta["Podcast metadata"]
  node_concerts["Concert recognition<br/>[music-metadata.js]"]
end

subgraph group_platforms["Device access"]
  node_androidtv["Android TV app<br/>[MainActivity.java]"]
  node_tvpicker["TV server picker<br/>[wrapper.js]"]
  node_tray["Windows tray launcher"]
  node_traywrapper["Server wrapper<br/>[server.js]"]
end

node_viewer(("Viewer"))
node_wikiapi(("AKB48 Wiki"))
node_browser(("Browser"))
node_discord(("Discord"))

node_viewer -->|"browses"| node_hub
node_hub -->|"requests views"| node_spa
node_spa -->|"fetches library"| node_library
node_library -->|"scans media"| node_mediafiles
node_library -->|"enriches items"| node_musicmeta
node_library -->|"attaches song data"| node_concerts
node_spa -->|"controls playback"| node_cinema
node_spa -->|"controls music"| node_listen
node_spa -->|"opens podcasts"| node_podcast
node_listen -->|"uses metadata"| node_musicmeta
node_podcast -->|"uses metadata"| node_podmeta
node_spa -->|"stores progress"| node_watch
node_spa -->|"requests articles"| node_wiki
node_wiki -.->|"fetches wiki data"| node_wikiapi
node_browser -->|"loads application"| node_spa
node_browser -->|"opens picker"| node_tvpicker
node_tvpicker -->|"probes health"| node_server
node_tvpicker -->|"opens TV view"| node_tvmode
node_androidtv -->|"probes and loads"| node_server
node_tvmode -->|"navigates interface"| node_spa
node_tray -->|"starts server"| node_traywrapper
node_traywrapper -->|"loads entry point"| node_server
node_server -.->|"updates status"| node_presence
node_presence -.->|"sends presence"| node_discord

click node_spa "https://github.com/karaagexc/akb48-archive/blob/main/app/web-app/public/js/spa.js"
click node_hub "https://github.com/karaagexc/akb48-archive/blob/main/app/web-app/public/js/hub.js"
click node_listen "https://github.com/karaagexc/akb48-archive/blob/main/app/web-app/public/js/listen.js"
click node_podcast "https://github.com/karaagexc/akb48-archive/blob/main/app/web-app/public/js/podcast.js"
click node_cinema "https://github.com/karaagexc/akb48-archive/blob/main/app/web-app/public/js/video-player.js"
click node_tvmode "https://github.com/karaagexc/akb48-archive/blob/main/tv/tv.js"
click node_server "https://github.com/karaagexc/akb48-archive/blob/main/app/web-app/server.js"
click node_library "https://github.com/karaagexc/akb48-archive/blob/main/app/web-app/server.js"
click node_watch "https://github.com/karaagexc/akb48-archive/blob/main/app/web-app/server.js"
click node_wiki "https://github.com/karaagexc/akb48-archive/blob/main/app/web-app/server.js"
click node_musicmeta "https://github.com/karaagexc/akb48-archive/blob/main/app/web-app/lib/music-metadata.js"
click node_podmeta "https://github.com/karaagexc/akb48-archive/blob/main/app/web-app/lib/podcast-metadata.js"
click node_concerts "https://github.com/karaagexc/akb48-archive/blob/main/app/web-app/lib/music-metadata.js"
click node_androidtv "https://github.com/karaagexc/akb48-archive/blob/main/tv-android/app/src/main/java/com/akb48archive/tv/MainActivity.java"
click node_tvpicker "https://github.com/karaagexc/akb48-archive/blob/main/tv-app/wrapper.js"
click node_tray "https://github.com/karaagexc/akb48-archive/blob/main/app/windows-tray/AKB48ArchiveTray.cs"
click node_traywrapper "https://github.com/karaagexc/akb48-archive/blob/main/app/windows-tray/server.js"
click node_presence "https://github.com/karaagexc/akb48-archive/blob/main/app/web-app/server.js"

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_spa,node_hub,node_listen,node_podcast,node_cinema,node_tvmode,node_viewer,node_browser toneBlue
class node_server,node_library,node_watch,node_wiki,node_mediafiles,node_presence toneAmber
class node_musicmeta,node_podmeta,node_concerts toneMint
class node_androidtv,node_tvpicker,node_tray,node_traywrapper toneRose
class node_wikiapi,node_discord toneIndigo
```

## Components

### Web experience

- [SPA controller](https://github.com/karaagexc/akb48-archive/blob/main/app/web-app/public/js/spa.js): `app/web-app/public/js/spa.js`
- [Hub and browse](https://github.com/karaagexc/akb48-archive/blob/main/app/web-app/public/js/hub.js): `app/web-app/public/js/hub.js`
- [Music view](https://github.com/karaagexc/akb48-archive/blob/main/app/web-app/public/js/listen.js): `app/web-app/public/js/listen.js`
- [Podcast view](https://github.com/karaagexc/akb48-archive/blob/main/app/web-app/public/js/podcast.js): `app/web-app/public/js/podcast.js`
- [Video player](https://github.com/karaagexc/akb48-archive/blob/main/app/web-app/public/js/video-player.js): `app/web-app/public/js/video-player.js`
- [TV navigation](https://github.com/karaagexc/akb48-archive/blob/main/tv/tv.js): `tv/tv.js`

### Archive backend

- [Express server](https://github.com/karaagexc/akb48-archive/blob/main/app/web-app/server.js): `app/web-app/server.js`
- [Library API](https://github.com/karaagexc/akb48-archive/blob/main/app/web-app/server.js): `app/web-app/server.js`
- [Watch progress](https://github.com/karaagexc/akb48-archive/blob/main/app/web-app/server.js): `app/web-app/server.js`
- [Wiki proxy](https://github.com/karaagexc/akb48-archive/blob/main/app/web-app/server.js): `app/web-app/server.js`
- **Media library**
- [Discord presence](https://github.com/karaagexc/akb48-archive/blob/main/app/web-app/server.js): `app/web-app/server.js`

### Media features

- [Music metadata](https://github.com/karaagexc/akb48-archive/blob/main/app/web-app/lib/music-metadata.js): `app/web-app/lib/music-metadata.js`
- [Podcast metadata](https://github.com/karaagexc/akb48-archive/blob/main/app/web-app/lib/podcast-metadata.js): `app/web-app/lib/podcast-metadata.js`
- [Concert recognition](https://github.com/karaagexc/akb48-archive/blob/main/app/web-app/lib/music-metadata.js): `app/web-app/lib/music-metadata.js`

### Device access

- [Android TV app](https://github.com/karaagexc/akb48-archive/blob/main/tv-android/app/src/main/java/com/akb48archive/tv/MainActivity.java): `tv-android/app/src/main/java/com/akb48archive/tv/MainActivity.java`
- [TV server picker](https://github.com/karaagexc/akb48-archive/blob/main/tv-app/wrapper.js): `tv-app/wrapper.js`
- [Windows tray launcher](https://github.com/karaagexc/akb48-archive/blob/main/app/windows-tray/AKB48ArchiveTray.cs): `app/windows-tray/AKB48ArchiveTray.cs`
- [Server wrapper](https://github.com/karaagexc/akb48-archive/blob/main/app/windows-tray/server.js): `app/windows-tray/server.js`

### Other components

- **Viewer**
- **AKB48 Wiki**
- **Browser**
- **Discord**

## Connections

- Viewer → Hub and browse: browses
- Hub and browse → SPA controller: requests views
- SPA controller → Library API: fetches library
- Library API → Media library: scans media
- Library API → Music metadata: enriches items
- Library API → Concert recognition: attaches song data
- SPA controller → Video player: controls playback
- SPA controller → Music view: controls music
- SPA controller → Podcast view: opens podcasts
- Music view → Music metadata: uses metadata
- Podcast view → Podcast metadata: uses metadata
- SPA controller → Watch progress: stores progress
- SPA controller → Wiki proxy: requests articles
- Wiki proxy → AKB48 Wiki: fetches wiki data
- Browser → SPA controller: loads application
- Browser → TV server picker: opens picker
- TV server picker → Express server: probes health
- TV server picker → TV navigation: opens TV view
- Android TV app → Express server: probes and loads
- TV navigation → SPA controller: navigates interface
- Windows tray launcher → Server wrapper: starts server
- Server wrapper → Express server: loads entry point
- Express server → Discord presence: updates status
- Discord presence → Discord: sends presence