# lucascoppola/music-player architecture

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

- Interactive diagram: https://gitdiagram.com/lucascoppola/music-player
- Repository: https://github.com/lucascoppola/music-player

## Overview

##### Main Components

A. Client Layer (Frontend):
- React Application Container
- Authentication Module
- Music Player Module
- Playlist Management Module
- File Upload Module
- Search Module

B. Server Layer (Backend):
- NestJS Application Container
- Auth Module
- Users Module
- Track Module
- Playlist Module
- File Module

C. Storage Layer:
- PostgreSQL Database
- File System Storage (Docker Volumes)
- Audio Files Storage
- Image Files Storage

D. External Services:
- AWS EC2 Host
- CI/CD Pipeline (GitHub Actions)

##### Component Relationships and Data Flow

**Client Layer → API Layer → Service Layer → Storage Layer**

##### Specific Implementation Details

Frontend Section:
- React components hierarchy
- TanStack Router for routing
- React Query for data fetching
- Shadcn/ui components integration

Backend Section:
- NestJS module structure
- Authentication flow with JWT
- File processing pipelines (FFmpeg for audio, Sharp for images)
- Database entity relationships

##### Important Architectural Patterns to Highlight

- Module-based architecture in NestJS
- Component-based architecture in React
- MVC pattern in the backend
- Repository pattern for data access
- Provider pattern for context management

##### Technical Details

Annotations for:
- Docker container boundaries
- Network boundaries
- Security layers
- Caching mechanisms
- File processing workflows

##### Infrastructure Components

Deployment-related elements:
- Docker containers
- AWS EC2 instance
- GitHub Actions workflow
- Volume mounts for persistent storage

## Diagram (Mermaid)

```mermaid
graph TB
    subgraph Client["Client Layer"]
        direction TB
        React["React Application"]
        AuthMod["Authentication Module"]
        PlayerMod["Music Player Module"]
        PlaylistMod["Playlist Management"]
        UploadMod["File Upload Module"]
        SearchMod["Search Module"]
        Context["Context Management"]
        
        React --> AuthMod
        React --> PlayerMod
        React --> PlaylistMod
        React --> UploadMod
        React --> SearchMod
        React --> Context
    end

    subgraph Server["Server Layer"]
        direction TB
        NestJS["NestJS Application"]
        AuthService["Auth Module"]
        UsersService["Users Module"]
        TrackService["Track Module"]
        PlaylistService["Playlist Module"]
        FileService["File Module"]
        
        NestJS --> AuthService
        NestJS --> UsersService
        NestJS --> TrackService
        NestJS --> PlaylistService
        NestJS --> FileService
    end

    subgraph Storage["Storage Layer"]
        direction TB
        DB[(PostgreSQL)]
        FileStore["File System Storage"]
        AudioFiles["Audio Files"]
        ImageFiles["Image Files"]
        
        FileStore --> AudioFiles
        FileStore --> ImageFiles
    end

    subgraph External["External Services"]
        direction TB
        AWS["AWS EC2"]
        CICD["GitHub Actions"]
        Docker["Docker Containers"]
    end

    %% Main connections
    Client -- "REST API" --> Server
    Server -. "Database Operations" .-> DB
    Server -- "File Operations" --> FileStore
    External --> Server

    %% Click events
    click AuthMod "https://github.com/LucasCoppola/music-player/tree/main/frontend/src/components/auth"
    click PlayerMod "https://github.com/LucasCoppola/music-player/tree/main/frontend/src/components/playback-controls"
    click PlaylistMod "https://github.com/LucasCoppola/music-player/blob/main/frontend/src/components/main/playlist.tsx"
    click UploadMod "https://github.com/LucasCoppola/music-player/tree/main/frontend/src/components/sidebar/upload"
    click SearchMod "https://github.com/LucasCoppola/music-player/blob/main/frontend/src/components/sidebar/search.tsx"
    click AuthService "https://github.com/LucasCoppola/music-player/tree/main/backend/src/auth"
    click UsersService "https://github.com/LucasCoppola/music-player/tree/main/backend/src/users"
    click TrackService "https://github.com/LucasCoppola/music-player/tree/main/backend/src/track"
    click PlaylistService "https://github.com/LucasCoppola/music-player/tree/main/backend/src/playlist"
    click FileService "https://github.com/LucasCoppola/music-player/tree/main/backend/src/file"
    click AudioFiles "https://github.com/LucasCoppola/music-player/tree/main/frontend/src/assets/tracks"
    click ImageFiles "https://github.com/LucasCoppola/music-player/tree/main/frontend/src/assets/images"
    click Docker "https://github.com/LucasCoppola/music-player/blob/main/docker-compose.yml"
    click CICD "https://github.com/LucasCoppola/music-player/blob/main/.github/workflows/ci.yml"
    click Context "https://github.com/LucasCoppola/music-player/blob/main/frontend/src/context/auth-context.tsx"

    %% Styling
    classDef frontend fill:#3498db,color:white
    classDef backend fill:#2ecc71,color:white
    classDef storage fill:#f1c40f,color:black
    classDef external fill:#95a5a6,color:white
    classDef security fill:#e74c3c,color:white

    class React,AuthMod,PlayerMod,PlaylistMod,UploadMod,SearchMod,Context frontend
    class NestJS,AuthService,UsersService,TrackService,PlaylistService,FileService backend
    class DB,FileStore,AudioFiles,ImageFiles storage
    class AWS,CICD,Docker external
    class AuthService,AuthMod security
```
