# sruckh/minmaxmusic3-web architecture

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

## Overview

MiniMax Music 3 Web is a self-hosted, multi-user music-generation console with optional YuE2 support. Users submit lyrics and style, optionally get an engine-specific AI draft, and queue a song; a background worker submits and polls inference jobs, stores audio and scores, and makes results available in song, history, and sharing views. YuE2 also supports score-based edits and recording covers from library items, uploads, or URLs. The graph reflects documented capabilities; some feature wiring is inferred only to the extent supported by the README and sampled files.

Main entry points: [`internal/server/server.go`](https://github.com/sruckh/minmaxmusic3-web/blob/main/internal/server/server.go) (HTTP server), [`internal/worker/worker.go`](https://github.com/sruckh/minmaxmusic3-web/blob/main/internal/worker/worker.go) (Job worker), [`internal/store/store.go`](https://github.com/sruckh/minmaxmusic3-web/blob/main/internal/store/store.go) (Application store), [`internal/server/handlers.go`](https://github.com/sruckh/minmaxmusic3-web/blob/main/internal/server/handlers.go) (Song handlers)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web and access"]
  node_browser["Web interface"]
  node_routes["HTTP server<br/>[server.go]"]
  node_auth["Authentication<br/>[auth.go]"]
  node_admin["Administration<br/>[admin.go]"]
  node_config["Runtime configuration<br/>[config.go]"]
end

subgraph group_creation["Song creation"]
  node_feature_handlers["Song handlers<br/>[handlers.go]"]
  node_cover["Cover handling<br/>[cover.go]"]
  node_assistant["Draft assistant<br/>[llm.go]"]
end

subgraph group_inference["Inference pipeline"]
  node_worker["Job worker<br/>[worker.go]"]
  node_runpod_client["Inference client<br/>[runpod.go]"]
  node_audio["Audio transcoder<br/>[audio.go]"]
end

subgraph group_library["Songs and accounts"]
  node_store[("Application store<br/>[store.go]")]
  node_audio_files[("Audio and score files")]
  node_history["History views<br/>[history.html]"]
  node_song_views["Song views<br/>[song.html]"]
  node_cover_links["Signed cover links<br/>[cover.go]"]
end

node_user(("User"))
node_llm_service["Chat service"]
node_runpod["RunPod engines"]
node_ffmpeg["FFmpeg"]

node_user -->|"uses"| node_browser
node_browser -->|"sends requests"| node_routes
node_routes -->|"authenticates"| node_auth
node_routes -->|"dispatches"| node_feature_handlers
node_routes -->|"dispatches"| node_admin
node_feature_handlers -->|"queues jobs"| node_store
node_feature_handlers -->|"requests drafts"| node_assistant
node_assistant -.->|"calls"| node_llm_service
node_feature_handlers -->|"handles covers"| node_cover
node_cover -->|"reads and writes"| node_store
node_cover -->|"mints links"| node_cover_links
node_cover_links -->|"stores token hashes"| node_store
node_routes -->|"runs workers"| node_worker
node_worker -->|"claims and updates jobs"| node_store
node_worker -->|"submits and polls"| node_runpod_client
node_runpod_client -->|"calls"| node_runpod
node_worker -->|"transcodes audio"| node_audio
node_audio -->|"invokes"| node_ffmpeg
node_worker -->|"writes audio and scores"| node_audio_files
node_worker -->|"records songs"| node_store
node_admin -->|"manages accounts"| node_store
node_auth -->|"reads and writes accounts"| node_store
node_routes -->|"renders"| node_history
node_routes -->|"renders"| node_song_views
node_history -->|"shows songs"| node_user
node_song_views -->|"shows results"| node_user
node_config -->|"configures"| node_routes

click node_browser "https://github.com/sruckh/minmaxmusic3-web/tree/main/web/templates"
click node_routes "https://github.com/sruckh/minmaxmusic3-web/blob/main/internal/server/server.go"
click node_auth "https://github.com/sruckh/minmaxmusic3-web/blob/main/internal/server/auth.go"
click node_admin "https://github.com/sruckh/minmaxmusic3-web/blob/main/internal/server/admin.go"
click node_feature_handlers "https://github.com/sruckh/minmaxmusic3-web/blob/main/internal/server/handlers.go"
click node_cover "https://github.com/sruckh/minmaxmusic3-web/blob/main/internal/server/cover.go"
click node_assistant "https://github.com/sruckh/minmaxmusic3-web/blob/main/internal/llm/llm.go"
click node_worker "https://github.com/sruckh/minmaxmusic3-web/blob/main/internal/worker/worker.go"
click node_runpod_client "https://github.com/sruckh/minmaxmusic3-web/blob/main/internal/runpod/runpod.go"
click node_audio "https://github.com/sruckh/minmaxmusic3-web/blob/main/internal/audio/audio.go"
click node_store "https://github.com/sruckh/minmaxmusic3-web/blob/main/internal/store/store.go"
click node_audio_files "https://github.com/sruckh/minmaxmusic3-web/tree/main/output"
click node_history "https://github.com/sruckh/minmaxmusic3-web/blob/main/web/templates/history.html"
click node_song_views "https://github.com/sruckh/minmaxmusic3-web/blob/main/web/templates/song.html"
click node_cover_links "https://github.com/sruckh/minmaxmusic3-web/blob/main/internal/server/cover.go"
click node_config "https://github.com/sruckh/minmaxmusic3-web/blob/main/internal/config/config.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_browser,node_routes,node_auth,node_admin,node_config,node_user toneBlue
class node_feature_handlers,node_cover,node_assistant toneAmber
class node_worker,node_runpod_client,node_audio toneMint
class node_store,node_audio_files,node_history,node_song_views,node_cover_links toneRose
class node_llm_service,node_runpod,node_ffmpeg toneIndigo
```

## Components

### Web and access

- [Web interface](https://github.com/sruckh/minmaxmusic3-web/tree/main/web/templates): `web/templates`
- [HTTP server](https://github.com/sruckh/minmaxmusic3-web/blob/main/internal/server/server.go): `internal/server/server.go`
- [Authentication](https://github.com/sruckh/minmaxmusic3-web/blob/main/internal/server/auth.go): `internal/server/auth.go`
- [Administration](https://github.com/sruckh/minmaxmusic3-web/blob/main/internal/server/admin.go): `internal/server/admin.go`
- [Runtime configuration](https://github.com/sruckh/minmaxmusic3-web/blob/main/internal/config/config.go): `internal/config/config.go`

### Song creation

- [Song handlers](https://github.com/sruckh/minmaxmusic3-web/blob/main/internal/server/handlers.go): `internal/server/handlers.go`
- [Cover handling](https://github.com/sruckh/minmaxmusic3-web/blob/main/internal/server/cover.go): `internal/server/cover.go`
- [Draft assistant](https://github.com/sruckh/minmaxmusic3-web/blob/main/internal/llm/llm.go): `internal/llm/llm.go`

### Inference pipeline

- [Job worker](https://github.com/sruckh/minmaxmusic3-web/blob/main/internal/worker/worker.go): `internal/worker/worker.go`
- [Inference client](https://github.com/sruckh/minmaxmusic3-web/blob/main/internal/runpod/runpod.go): `internal/runpod/runpod.go`
- [Audio transcoder](https://github.com/sruckh/minmaxmusic3-web/blob/main/internal/audio/audio.go): `internal/audio/audio.go`

### Songs and accounts

- [Application store](https://github.com/sruckh/minmaxmusic3-web/blob/main/internal/store/store.go): `internal/store/store.go`
- [Audio and score files](https://github.com/sruckh/minmaxmusic3-web/tree/main/output): `output`
- [History views](https://github.com/sruckh/minmaxmusic3-web/blob/main/web/templates/history.html): `web/templates/history.html`
- [Song views](https://github.com/sruckh/minmaxmusic3-web/blob/main/web/templates/song.html): `web/templates/song.html`
- [Signed cover links](https://github.com/sruckh/minmaxmusic3-web/blob/main/internal/server/cover.go): `internal/server/cover.go`

### Other components

- **User**
- **Chat service**
- **RunPod engines**
- **FFmpeg**

## Connections

- User → Web interface: uses
- Web interface → HTTP server: sends requests
- HTTP server → Authentication: authenticates
- HTTP server → Song handlers: dispatches
- HTTP server → Administration: dispatches
- Song handlers → Application store: queues jobs
- Song handlers → Draft assistant: requests drafts
- Draft assistant → Chat service: calls
- Song handlers → Cover handling: handles covers
- Cover handling → Application store: reads and writes
- Cover handling → Signed cover links: mints links
- Signed cover links → Application store: stores token hashes
- HTTP server → Job worker: runs workers
- Job worker → Application store: claims and updates jobs
- Job worker → Inference client: submits and polls
- Inference client → RunPod engines: calls
- Job worker → Audio transcoder: transcodes audio
- Audio transcoder → FFmpeg: invokes
- Job worker → Audio and score files: writes audio and scores
- Job worker → Application store: records songs
- Administration → Application store: manages accounts
- Authentication → Application store: reads and writes accounts
- HTTP server → History views: renders
- HTTP server → Song views: renders
- History views → User: shows songs
- Song views → User: shows results
- Runtime configuration → HTTP server: configures