# espeon/muse architecture

> Architecture diagram of the GitHub repository espeon/muse, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-01-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/espeon/muse
- Repository: https://github.com/espeon/muse

## Overview

##### Main Components Identification

The system consists of several key services:
- Maki: The core music server (Rust-based)
- Nozomi: The frontend application (Next.js-based)
- Eli: Remote control server
- Umi: Lyrics service (optional component)
- (Future) Honoka: Sōzu control plane

##### Component Relationships

- HTTP/WebSocket communication between frontend and backend services
- Database connections
- File system access patterns
- Authentication flows
- Media streaming paths

##### Technical Details to Highlight

- Supported audio formats (MP3, WAV, FLAC, AIFF)
- Database migrations
- API middleware (HMAC, JWT)
- File metadata extraction
- Frontend state management (stores/)
- Docker containerization

Create clear boundaries between:
- User Interface Layer
- Application Services
- Data Storage
- External Services
- Infrastructure Components

##### Additional Elements

Annotations for:
- Scaling points
- Security boundaries
- Optional components
- Future expansion points (recommendation engine, analytics)

Remember to indicate the containerized nature of the deployment and how the services interact within the Docker network. Also, highlight the optional nature of some components (like Umi) and how the system gracefully handles their absence.

This architecture should emphasize the system's ability to handle large music collections efficiently while maintaining low resource usage, as mentioned in the key features.

## Diagram (Mermaid)

```mermaid
graph TB
    %% Styles and Classes
    classDef frontend fill:#3498db,color:white
    classDef backend fill:#2ecc71,color:white
    classDef storage fill:#9b59b6,color:white
    classDef auth fill:#e74c3c,color:white
    classDef support fill:#f1c40f,color:black
    classDef external fill:#95a5a6,color:white
    classDef client fill:#34495e,color:white

    %% Client Layer
    subgraph Clients
        Browser["Web Browsers"]:::client
        RemoteClients["Remote Control Clients"]:::client
    end

    %% Frontend Layer
    subgraph Nozomi["Nozomi Frontend"]
        NextApp["Next.js Application"]:::frontend
        APIRoutes["API Routes"]:::frontend
        AuthUI["Authentication UI"]:::frontend
        PlayerComp["Player Components"]:::frontend
        UIComp["UI Components"]:::frontend
        StateManagement["State Management"]:::frontend
    end

    %% Backend Services
    subgraph BackendServices["Backend Services"]
        subgraph Maki["Maki Music Server"]
            MakiAPI["API Endpoints"]:::backend
            MetadataProc["Metadata Processing"]:::backend
            FSIntegration["File System Integration"]:::backend
            DBIntegration["Database Integration"]:::backend
        end

        EliServer["Eli Remote Control"]:::support
        UmiService["Umi Lyrics Service"]:::support
        AuthService["Authentication (OIDC)"]:::auth
    end

    %% Storage Layer
    subgraph Storage["Storage Layer"]
        MusicFiles["Music Files Storage"]:::storage
        PostgreSQL["PostgreSQL Database"]:::storage
        MetadataCache["Metadata Cache"]:::storage
    end

    %% External Services
    LastFM["LastFM Integration"]:::external
    OIDC["OIDC Provider"]:::external

    %% Relationships
    Browser --> NextApp
    RemoteClients --> EliServer
    NextApp --> APIRoutes
    APIRoutes --> MakiAPI
    NextApp --> AuthUI
    AuthUI --> AuthService
    AuthService --> OIDC
    PlayerComp --> MakiAPI
    MakiAPI --> MetadataProc
    MetadataProc --> FSIntegration
    FSIntegration --> MusicFiles
    DBIntegration --> PostgreSQL
    MakiAPI --> LastFM
    EliServer --> MakiAPI
    UmiService --> MakiAPI

    %% Click Events
    click NextApp "https://github.com/espeon/muse/tree/main/nozomi/src/app/"
    click APIRoutes "https://github.com/espeon/muse/tree/main/nozomi/src/app/api/"
    click AuthUI "https://github.com/espeon/muse/tree/main/nozomi/src/components/auth/"
    click PlayerComp "https://github.com/espeon/muse/blob/main/nozomi/src/components/player.tsx"
    click UIComp "https://github.com/espeon/muse/tree/main/nozomi/src/components/ui/"
    click StateManagement "https://github.com/espeon/muse/tree/main/nozomi/src/stores/"
    click MakiAPI "https://github.com/espeon/muse/tree/main/maki/src/api/"
    click MetadataProc "https://github.com/espeon/muse/tree/main/maki/src/metadata/"
    click FSIntegration "https://github.com/espeon/muse/tree/main/maki/src/index/"
    click DBIntegration "https://github.com/espeon/muse/blob/main/maki/src/db.rs"
    click EliServer "https://github.com/espeon/muse/blob/main/eli/src/main.rs"
    click LastFM "https://github.com/espeon/muse/blob/main/maki/src/clients/lastfm.rs"
    click PostgreSQL "https://github.com/espeon/muse/tree/main/maki/migrations/"

    %% Legend
    subgraph Legend
        Client1["Client"]:::client
        Frontend1["Frontend"]:::frontend
        Backend1["Backend"]:::backend
        Storage1["Storage"]:::storage
        Auth1["Auth"]:::auth
        Support1["Support Services"]:::support
        External1["External Services"]:::external
    end
```
