# alexatsu/tune-legacy architecture

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

- Interactive diagram: https://gitdiagram.com/alexatsu/tune-legacy
- Repository: https://github.com/alexatsu/tune-legacy

## Overview

#### Purpose and deployment shape
Tune-legacy is a discontinued multi-source music application: users search, save, organize into albums/playlists, and stream music sourced through YouTube/Spotify (SoundCloud planned). It is a container-oriented microservice repository, coordinated locally by `docker-compose.yaml`, with CI/workflow automation under `.github/workflows/main.yaml`.

#### Primary user-facing application
The main product is a Next.js/TypeScript client with App Router pages, server-side API routes, authentication, and Prisma persistence.
- Web entry and global composition: `client/src/app/layout.tsx`, `client/src/app/page.tsx`, `client/src/middleware.ts`
- Auth boundary: `client/src/app/api/auth/[...nextauth]/route.ts`, `client/src/app/_/providers/SessionProvider.tsx`
- Music-area shell and shared player/navigation state: `client/src/app/(music)/layout.tsx`, `client/src/app/_/providers/PlayerProvider.tsx`, `client/src/app/(music)/_/providers/StreamProvider.tsx`

The UI is organized around music browsing/search, charts, albums, settings/themes, and an active player rather than a separate public API product.

#### Application API and persistence
Next.js route handlers form the client-facing backend boundary. They encapsulate database operations and service calls for songs, streaming, albums, charts, and preferences.
- Database access and schema evolution: `client/src/app/api/_/services/db.ts`, `client/prisma/schema.prisma`
- Song and stream endpoints: `client/src/app/api/songs/search/route.ts`, `client/src/app/api/songs/stream/route.ts`, `client/src/app/api/songs/add/route.ts`
- Album and theme mutations: `client/src/app/api/albums/create/route.ts`, `client/src/app/api/albums/add-or-delete-song/route.ts`, `client/src/app/api/settings/themes/update-current-theme/route.ts`

Prisma migrations indicate durable user, OAuth, music, album, and theme-related state. The exact database engine is not established by the supplied tree.

#### Music acquisition and streaming service
A Python service handles external music lookup, temporary listening/streaming, download/storage work, and audio models. Per the README, this layer uses `yt-dlp` to retrieve source metadata/audio and supplies media for client playback, with music ultimately wrapped in an iframe.
- Service entry and HTTP routing: `music-service/src/main.py`, `music-service/src/routes/search.py`
- Search, temporary stream, and storage pipeline: `music-service/src/controllers/search/searchSongs.py`, `music-service/src/controllers/search/streamTemporal.py`, `music-service/src/controllers/search/saveAndStore.py`
- Media acquisition/model boundary: `music-service/src/utils/functions/downloadSong.py`, `music-service/src/models/audio.py`

This service is the principal boundary between application-owned data and external content platforms.

#### Charts ingestion, processing, and presentation
Charts are a separate pipeline rather than being generated in the web app. A Node/TypeScript parser runs scheduled chart parsing, exposes/retrieves processed results, and can send them to backup; a Python charts service generates chart output consumed through the client’s charts API/UI.
- Parser startup, schedule, and chart controllers: `parser-service/main.ts`, `parser-service/src/cron/parseCharts.ts`, `parser-service/src/routes/charts/controllers/retrieveProcessedCharts.ts`
- Chart generation service: `charts-service/main.py`, `charts-service/routes/charts.py`, `charts-service/controllers/charts/generateCharts.py`
- Client integration: `client/src/app/api/charts/get-all/route.ts`, `client/src/app/(music)/charts/page.tsx`

#### Backup and external storage
A Bun/TypeScript backup service separates restoration and backup of charts/database data from request-serving components. Its Cloudinary utility identifies Cloudinary as an external storage integration.
- Backup service entry and operations: `backup-service/src/main.ts`, `backup-service/src/modules/backupCharts.ts`, `backup-service/src/modules/backupDB.ts`
- Restore/storage integration: `backup-service/src/modules/restore.ts`, `backup-service/src/utils/cloudinary.ts`
- Automation: `.github/workflows/backup.yaml`, `.github/workflows/charts.yaml`

#### Secondary desktop client
An early desktop implementation uses Wails: Go launches the native shell and a Vite/React frontend communicates through generated Wails bindings. It appears independent of the primary Next.js client and is not the main deployed product.
- Native entry points: `desktop/main.go`, `desktop/app.go`, `desktop/wails.json`
- Desktop frontend entry: `desktop/frontend/src/main.tsx`, `desktop/frontend/src/App.tsx`

Main entry points: [`docker-compose.yaml`](https://github.com/alexatsu/tune-legacy/blob/main/docker-compose.yaml) (Docker Compose), [`client/src/app/api/songs/search/route.ts`](https://github.com/alexatsu/tune-legacy/blob/main/client/src/app/api/songs/search/route.ts) (Application API), [`backup-service/src/modules/backupCharts.ts`](https://github.com/alexatsu/tune-legacy/blob/main/backup-service/src/modules/backupCharts.ts) (Backup operations), [`client/src/app/(music)/layout.tsx`](https://github.com/alexatsu/tune-legacy/blob/main/client/src/app/(music)/layout.tsx) (Music UI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Primary web app"]
  node_web_ui["Music UI<br/>Next.js App Router<br/>[layout.tsx]"]
  node_web_entry["Web entry<br/>Next.js composition<br/>[layout.tsx]"]
  node_auth["Authentication<br/>NextAuth session<br/>[route.ts]"]
  node_web_api["Application API<br/>Next.js route handlers<br/>[route.ts]"]
  node_prisma[("Prisma persistence<br/>database access<br/>[db.ts]")]
  node_schema["Prisma schema<br/>[schema.prisma]"]
  node_player_state["Player state<br/>React provider<br/>[PlayerProvider.tsx]"]
  node_charts_ui["Charts UI<br/>Next.js page<br/>[page.tsx]"]
end

subgraph group_music["Music service"]
  node_music_routes["Music HTTP routes<br/>Python routing<br/>[search.py]"]
  node_music_pipeline["Acquisition pipeline<br/>Python controllers<br/>[streamTemporal.py]"]
  node_media_download["Media download<br/>yt-dlp integration<br/>[downloadSong.py]"]
end

subgraph group_charts["Charts pipeline"]
  node_parser_scheduler["Chart parser scheduler<br/>Node cron<br/>[parseCharts.ts]"]
  node_processed_charts["Processed charts<br/>parser controller"]
  node_chart_generator["Chart generator<br/>Python service<br/>[generateCharts.py]"]
end

subgraph group_backup["Backup and storage"]
  node_backup_ops["Backup operations<br/>Bun service<br/>[backupCharts.ts]"]
end

subgraph group_desktop["Desktop client"]
  node_desktop_native["Wails native shell<br/>Go desktop host<br/>[main.go]"]
  node_desktop_ui["Desktop frontend<br/>Vite React<br/>[App.tsx]"]
end

node_compose{{"Docker Compose<br/>orchestration"}}
node_content_platforms(("Music platforms<br/>external sources"))
node_cloudinary(("Cloudinary<br/>external storage"))
node_workflows{{"CI and scheduled workflows<br/>GitHub Actions<br/>[main.yaml]"}}

node_compose -->|"runs"| node_web_entry
node_compose -->|"runs"| node_music_routes
node_compose -->|"runs"| node_parser_scheduler
node_compose -->|"runs"| node_chart_generator
node_compose -->|"runs"| node_backup_ops
node_web_entry -->|"composes"| node_web_ui
node_web_ui -->|"uses session"| node_auth
node_web_ui -->|"shares playback"| node_player_state
node_web_ui -->|"calls"| node_web_api
node_web_api -->|"persists through"| node_prisma
node_schema -->|"defines models"| node_prisma
node_web_api -->|"searches and streams"| node_music_routes
node_music_routes -->|"dispatches"| node_music_pipeline
node_music_pipeline -->|"acquires media"| node_media_download
node_media_download -->|"retrieves from"| node_content_platforms
node_parser_scheduler -->|"produces"| node_processed_charts
node_processed_charts -->|"supplies input"| node_chart_generator
node_web_api -->|"retrieves charts"| node_chart_generator
node_charts_ui -->|"requests charts"| node_web_api
node_parser_scheduler -.->|"backs up charts"| node_backup_ops
node_backup_ops -.->|"backs up and restores"| node_prisma
node_backup_ops -->|"stores backups"| node_cloudinary
node_workflows -.->|"triggers chart jobs"| node_parser_scheduler
node_workflows -.->|"triggers backups"| node_backup_ops
node_desktop_native -->|"hosts"| node_desktop_ui

click node_compose "https://github.com/alexatsu/tune-legacy/blob/main/docker-compose.yaml"
click node_web_ui "https://github.com/alexatsu/tune-legacy/blob/main/client/src/app/(music)/layout.tsx"
click node_web_entry "https://github.com/alexatsu/tune-legacy/blob/main/client/src/app/layout.tsx"
click node_auth "https://github.com/alexatsu/tune-legacy/blob/main/client/src/app/api/auth/%5B...nextauth%5D/route.ts"
click node_web_api "https://github.com/alexatsu/tune-legacy/blob/main/client/src/app/api/songs/search/route.ts"
click node_prisma "https://github.com/alexatsu/tune-legacy/blob/main/client/src/app/api/_/services/db.ts"
click node_schema "https://github.com/alexatsu/tune-legacy/blob/main/client/prisma/schema.prisma"
click node_player_state "https://github.com/alexatsu/tune-legacy/blob/main/client/src/app/_/providers/PlayerProvider.tsx"
click node_music_routes "https://github.com/alexatsu/tune-legacy/blob/main/music-service/src/routes/search.py"
click node_music_pipeline "https://github.com/alexatsu/tune-legacy/blob/main/music-service/src/controllers/search/streamTemporal.py"
click node_media_download "https://github.com/alexatsu/tune-legacy/blob/main/music-service/src/utils/functions/downloadSong.py"
click node_parser_scheduler "https://github.com/alexatsu/tune-legacy/blob/main/parser-service/src/cron/parseCharts.ts"
click node_processed_charts "https://github.com/alexatsu/tune-legacy/blob/main/parser-service/src/routes/charts/controllers/retrieveProcessedCharts.ts"
click node_chart_generator "https://github.com/alexatsu/tune-legacy/blob/main/charts-service/controllers/charts/generateCharts.py"
click node_charts_ui "https://github.com/alexatsu/tune-legacy/blob/main/client/src/app/(music)/charts/page.tsx"
click node_backup_ops "https://github.com/alexatsu/tune-legacy/blob/main/backup-service/src/modules/backupCharts.ts"
click node_workflows "https://github.com/alexatsu/tune-legacy/blob/main/.github/workflows/main.yaml"
click node_desktop_native "https://github.com/alexatsu/tune-legacy/blob/main/desktop/main.go"
click node_desktop_ui "https://github.com/alexatsu/tune-legacy/blob/main/desktop/frontend/src/App.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_web_ui,node_web_entry,node_auth,node_web_api,node_prisma,node_schema,node_player_state,node_charts_ui toneBlue
class node_music_routes,node_music_pipeline,node_media_download toneAmber
class node_parser_scheduler,node_processed_charts,node_chart_generator toneMint
class node_backup_ops toneRose
class node_desktop_native,node_desktop_ui toneIndigo
class node_compose,node_content_platforms,node_cloudinary,node_workflows toneNeutral
```

## Components

### Primary web app

Next.js client and its server-side API boundary.

- [Music UI](https://github.com/alexatsu/tune-legacy/blob/main/client/src/app/(music)/layout.tsx): Next.js App Router · Browse, search, organize music, and play streams. · `client/src/app/(music)/layout.tsx`
- [Web entry](https://github.com/alexatsu/tune-legacy/blob/main/client/src/app/layout.tsx): Next.js composition · Global layout, landing page, and middleware. · `client/src/app/layout.tsx`
- [Authentication](https://github.com/alexatsu/tune-legacy/blob/main/client/src/app/api/auth/%5B...nextauth%5D/route.ts): NextAuth session · Auth route and client session boundary. · `client/src/app/api/auth/[...nextauth]/route.ts`
- [Application API](https://github.com/alexatsu/tune-legacy/blob/main/client/src/app/api/songs/search/route.ts): Next.js route handlers · Client-facing backend for music, albums, themes, and charts. · `client/src/app/api/songs/search/route.ts`
- [Prisma persistence](https://github.com/alexatsu/tune-legacy/blob/main/client/src/app/api/_/services/db.ts): database access · Durable user, OAuth, music, album, and theme state. · `client/src/app/api/_/services/db.ts`
- [Prisma schema](https://github.com/alexatsu/tune-legacy/blob/main/client/prisma/schema.prisma): schema · `client/prisma/schema.prisma`
- [Player state](https://github.com/alexatsu/tune-legacy/blob/main/client/src/app/_/providers/PlayerProvider.tsx): React provider · Shared player and stream state. · `client/src/app/_/providers/PlayerProvider.tsx`
- [Charts UI](https://github.com/alexatsu/tune-legacy/blob/main/client/src/app/(music)/charts/page.tsx): Next.js page · `client/src/app/(music)/charts/page.tsx`

### Music service

Python acquisition and temporary streaming boundary.

- [Music HTTP routes](https://github.com/alexatsu/tune-legacy/blob/main/music-service/src/routes/search.py): Python routing · Search and media requests enter the music service here. · `music-service/src/routes/search.py`
- [Acquisition pipeline](https://github.com/alexatsu/tune-legacy/blob/main/music-service/src/controllers/search/streamTemporal.py): Python controllers · Searches sources, creates temporary streams, and stores media. · `music-service/src/controllers/search/streamTemporal.py`
- [Media download](https://github.com/alexatsu/tune-legacy/blob/main/music-service/src/utils/functions/downloadSong.py): yt-dlp integration · Retrieves source metadata and audio. · `music-service/src/utils/functions/downloadSong.py`

### Charts pipeline

Scheduled parsing and generated chart delivery.

- [Chart parser scheduler](https://github.com/alexatsu/tune-legacy/blob/main/parser-service/src/cron/parseCharts.ts): Node cron · Runs scheduled chart parsing. · `parser-service/src/cron/parseCharts.ts`
- [Processed charts](https://github.com/alexatsu/tune-legacy/blob/main/parser-service/src/routes/charts/controllers/retrieveProcessedCharts.ts): parser controller · Retrieves processed parser results. · `parser-service/src/routes/charts/controllers/retrieveProcessedCharts.ts`
- [Chart generator](https://github.com/alexatsu/tune-legacy/blob/main/charts-service/controllers/charts/generateCharts.py): Python service · Generates chart output for consumers. · `charts-service/controllers/charts/generateCharts.py`

### Backup and storage

Backup, restore, and external storage operations.

- [Backup operations](https://github.com/alexatsu/tune-legacy/blob/main/backup-service/src/modules/backupCharts.ts): Bun service · Backs up charts and database data and restores them. · `backup-service/src/modules/backupCharts.ts`

### Desktop client

Independent early Wails implementation.

- [Wails native shell](https://github.com/alexatsu/tune-legacy/blob/main/desktop/main.go): Go desktop host · Launches the independent desktop application. · `desktop/main.go`
- [Desktop frontend](https://github.com/alexatsu/tune-legacy/blob/main/desktop/frontend/src/App.tsx): Vite React · Uses generated Wails bindings to communicate with Go. · `desktop/frontend/src/App.tsx`

### Other components

- [Docker Compose](https://github.com/alexatsu/tune-legacy/blob/main/docker-compose.yaml): orchestration · Coordinates local multi-service deployment. · `docker-compose.yaml`
- **Music platforms**: external sources · YouTube and Spotify content sources.
- **Cloudinary**: external storage
- [CI and scheduled workflows](https://github.com/alexatsu/tune-legacy/blob/main/.github/workflows/main.yaml): GitHub Actions · Build automation plus chart and backup jobs. · `.github/workflows/main.yaml`

## Connections

- Docker Compose → Web entry: runs
- Docker Compose → Music HTTP routes: runs
- Docker Compose → Chart parser scheduler: runs
- Docker Compose → Chart generator: runs
- Docker Compose → Backup operations: runs
- Web entry → Music UI: composes
- Music UI → Authentication: uses session
- Music UI → Player state: shares playback
- Music UI → Application API: calls
- Application API → Prisma persistence: persists through
- Prisma schema → Prisma persistence: defines models
- Application API → Music HTTP routes: searches and streams
- Music HTTP routes → Acquisition pipeline: dispatches
- Acquisition pipeline → Media download: acquires media
- Media download → Music platforms: retrieves from
- Chart parser scheduler → Processed charts: produces
- Processed charts → Chart generator: supplies input
- Application API → Chart generator: retrieves charts
- Charts UI → Application API: requests charts
- Chart parser scheduler → Backup operations: backs up charts
- Backup operations → Prisma persistence: backs up and restores
- Backup operations → Cloudinary: stores backups
- CI and scheduled workflows → Chart parser scheduler: triggers chart jobs
- CI and scheduled workflows → Backup operations: triggers backups
- Wails native shell → Desktop frontend: hosts