# fatihege/rival-music architecture

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

- Interactive diagram: https://gitdiagram.com/fatihege/rival-music
- Repository: https://github.com/fatihege/rival-music

## Overview

##### Main Components
a. Client (Next.js/React) – SSR web application serving UI and static assets
b. API Server (Express.js/Node.js) – RESTful endpoints, business logic, controllers/models
c. Database (MongoDB) – persistent storage of users, tracks, playlists, artists, etc.
d. Cache (Redis) – in-memory store for session data, caching frequently accessed queries
e. Search Engine (MiniSearch) – full-text search index embedded in the API layer
f. External Services
- Mailer (SMTP via server/lib/mailer) for activation, password reset
- File storage (local filesystem or cloud) for uploaded audio via multer
g. Docker Compose – orchestration of containers for the above components

##### Relationships & Data Flows
- User’s browser ⇄ Next.js server:
– HTTP(S) requests for pages, API calls from client-side React components
– Server-Side Rendering of pages on initial load
- Next.js server → API server:
– Calls REST routes (e.g., `/api/track`, `/api/user`) defined in server/routes
- API server → MongoDB:
– CRUD via Mongoose models (`server/models/*.js`)
- API server ↔ Redis:
– Read/write cache for hot data (sessions, recent searches) via `server/lib/redis.js`
- API server → MiniSearch:
– Build and query in-memory index for fast full-text search of tracks, artists
- API server → Mail Service & File Storage:
– Send emails (`server/lib/mailer.js`), store/delete uploaded audio files (`server/lib/multer.js`)

##### Architectural Patterns & Principles
- SSR Pattern (Next.js) – improves SEO and initial-load performance
- MVC-style API – controllers (`server/controllers/*.js`), models (`server/models/*.js`), routes
- Middleware Pipeline – auth, admin checks (`server/middlewares/*.js`), input validation
- Caching Layer – Redis to reduce DB load and speed up responses
- Modular Frontend – React contexts, reusable components (`client/src/components`, `client/src/contexts`)
- Containerization – each service (client, server, MongoDB, Redis) runs in its own Docker container

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% User Browser
    Browser["User Browser"]:::frontend

    %% Frontend Layer
    subgraph "Frontend Layer (Next.js/React SSR)"
        direction TB
        NextJS["Next.js/React SSR"]:::frontend
        Pages["Pages"]:::frontend
        Components["UI Components"]:::frontend
        Contexts["React Contexts"]:::frontend
    end

    %% Backend Layer
    subgraph "Backend Layer (Express.js API)"
        direction TB
        APIServer["API Server (Express.js)"]:::backend
        subgraph "MVC & Middleware"
            direction TB
            Routes["API Routes"]:::backend
            Controllers["Controllers"]:::backend
            Models["Mongoose Models"]:::backend
            Middlewares["Middlewares"]:::backend
            Utils["Utilities"]:::backend
        end
    end

    %% Data & Cache
    subgraph "Data & Cache"
        direction TB
        MongoDB["MongoDB"]:::db
        Redis["Redis"]:::cache
        MiniSearch["MiniSearch Index"]:::cache
    end

    %% External Services
    subgraph "External Services"
        direction TB
        Mailer["SMTP Mailer"]:::external
        FileStore["File Storage"]:::external
    end

    %% Orchestration
    DockerCompose["Docker Compose"]:::compose

    %% Connections
    Browser -->|"HTTPS/HTML, JS bundle, SSR"| NextJS
    NextJS -->|"HTTPS/JSON REST calls"| APIServer
    APIServer -->|"Driver queries (Mongoose)"| MongoDB
    APIServer <-->|"GET/SET cache"| Redis
    APIServer -->|"Index/Query full-text"| MiniSearch
    APIServer -->|"SMTP send"| Mailer
    APIServer -->|"Store/Delete audio"| FileStore
    DockerCompose --> NextJS
    DockerCompose --> APIServer
    DockerCompose --> MongoDB
    DockerCompose --> Redis

    %% Click Events
    click NextJS "https://github.com/fatihege/rival-music/tree/main/client/"
    click Pages "https://github.com/fatihege/rival-music/tree/main/client/src/pages/"
    click Components "https://github.com/fatihege/rival-music/tree/main/client/src/components/"
    click Contexts "https://github.com/fatihege/rival-music/tree/main/client/src/contexts/"
    click APIServer "https://github.com/fatihege/rival-music/blob/main/server/index.js"
    click Routes "https://github.com/fatihege/rival-music/tree/main/server/routes/"
    click Controllers "https://github.com/fatihege/rival-music/tree/main/server/controllers/"
    click Models "https://github.com/fatihege/rival-music/tree/main/server/models/"
    click Middlewares "https://github.com/fatihege/rival-music/tree/main/server/middlewares/"
    click Utils "https://github.com/fatihege/rival-music/tree/main/server/utils/"
    click MongoDB "https://github.com/fatihege/rival-music/blob/main/server/config.js"
    click Redis "https://github.com/fatihege/rival-music/blob/main/server/lib/redis.js"
    click MiniSearch "https://github.com/fatihege/rival-music/blob/main/server/lib/search.js"
    click Mailer "https://github.com/fatihege/rival-music/blob/main/server/lib/mailer.js"
    click FileStore "https://github.com/fatihege/rival-music/blob/main/server/lib/multer.js"
    click DockerCompose "https://github.com/fatihege/rival-music/blob/main/compose.yaml"
    click DockerCompose "https://github.com/fatihege/rival-music/tree/main/client/Dockerfile"
    click DockerCompose "https://github.com/fatihege/rival-music/tree/main/server/Dockerfile"
    click Browser "https://github.com/fatihege/rival-music/blob/main/client/.env.example"
    click APIServer "https://github.com/fatihege/rival-music/blob/main/server/.env.example"

    %% Styles
    classDef frontend fill:#E0F7FA,stroke:#006064,color:#006064
    classDef backend fill:#E3F2FD,stroke:#0D47A1,color:#0D47A1
    classDef db fill:#FFE0B2,stroke:#EF6C00,color:#E65100
    classDef cache fill:#E1BEE7,stroke:#6A1B9A,color:#4A148C
    classDef external fill:#C8E6C9,stroke:#2E7D32,color:#1B5E20
    classDef compose fill:#F5F5F5,stroke:#424242,color:#212121
```
