# iammordaty/assistant-web architecture

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

- Interactive diagram: https://gitdiagram.com/iammordaty/assistant-web
- Repository: https://github.com/iammordaty/assistant-web

## Overview

##### Project Overview & Purpose
- That the application is a full-stack web tool for managing and analyzing music collections. It is built with PHP (using the Slim Framework), employs a modular structure to handle different functions (collection, search, directory management, mix, track handling), and integrates external audio processing libraries (Essentia for audio extraction and Musly for track similarity).
- The project also uses Docker for containerizing different parts of the system (e.g., PHP-FPM, Nginx, Music Classifier, Music Similarity) and leverages MongoDB as the database.

##### Main Components
a. User Interface / Frontend:
- “public” directory which contains the web assets (CSS, JavaScript, images, vendor code).
- Frameworks like jQuery and Bootstrap 5 (with Tabler dashboard template) that support the UI.

b. Backend Application Logic:
- “src” directory which is very modular and includes multiple submodules (Assistant, Collection, Dashboard, Directory, Mix, Search, Track). Each of these modules encapsulates specific responsibilities (like controllers, task management, reading/writing music metadata, similarity analysis, etc.).
- Use of the Slim Framework and Twig templating engine.
- Configuration and dependency injection files found in the “config” directory.

c. External Services & Libraries:
- Database: MongoDB (as per the README’s “stack”) which stores music collection data, logs, and possibly indexing information.
- External APIs: Beatport API integration for track and release information.
- Audio Processing Libraries: Essentia (via the music extractor) and Musly (for music similarity) integrated into the system.

d. Docker & Containerization:
- Detail the containers defined under the “.docker” directory:
- PHP-FPM container which runs the main PHP backend. This container also includes several binaries (e.g., Essentia streaming extractor, Musly) that perform audio feature extraction.
- Nginx container which acts as the reverse proxy and web server.
- Music Classifier and Music Similarity containers, which likely run specialized tasks related to analyzing audio features.
- “docker-compose.yml” to illustrate how these containers are orchestrated and interact with one another.

##### Architectural Relationships and Data Flow
- That incoming HTTP(S) requests from clients are handled by the Nginx container. From there, requests pass to the PHP-FPM container hosting the Slim application.
- Inside the PHP-FPM container, application logic is split into various modules to handle different requests—each module (Collection, Track, Search, Dashboard, etc.) has controllers, services, and tasks.
- When processing music files, the application interacts with:
- External audio extraction and similarity services (using Essentia and Musly, executed in separate containers or via binaries in PHP-FPM).
- The Beatport API through a dedicated API client module.
- The database layer (MongoDB) should be drawn as an independent component which the PHP application communicates with for persistence.

## Diagram (Mermaid)

```mermaid
graph TD
    %% Docker Containers Subgraph
    subgraph "Docker Containers"
        Nginx["Nginx - Web Server"]:::container
        PHPFPM["PHP-FPM - Application Server"]:::container
        MusicClassifierCont["Music Classifier Container"]:::container
        MusicSimilarityCont["Music Similarity Container"]:::container
        Compose["Container Orchestration (docker-compose.yml)"]:::container
    end

    %% Application Components Subgraph
    subgraph "Application Components"
        Frontend["Frontend Assets"]:::app
        Backend["Backend Application (src)"]:::app
        Config["Configuration (config)"]:::config
        CLI["CLI Tasks (bin/console.php)"]:::app
        Beatport["Beatport API Client"]:::external
        AudioProc["Audio Processing Binaries"]:::external
        MusicClassifierModule["Music Classifier Module"]:::app
    end

    %% External Entities
    User["User Browser"]:::external
    DB["MongoDB Database"]:::external

    %% Connections: User to Docker Containers
    User -->|"HTTP_Request"| Nginx
    Nginx -->|"Reverse_Proxy"| PHPFPM
    Compose --> Nginx
    Compose --> PHPFPM
    Compose --> MusicClassifierCont
    Compose --> MusicSimilarityCont

    %% Connections: PHP-FPM to Application Components and External Services
    PHPFPM -->|"Executes"| Backend
    Backend --> Config
    Backend --> AudioProc
    Backend --> Beatport
    Backend -->|"Background_Jobs"| CLI
    Backend -->|"Queries_Updates"| DB
    Backend --> MusicClassifierModule

    %% Delegation from PHP-FPM to Specialized Containers
    PHPFPM -->|"Delegates_Audio_Tasks"| MusicClassifierCont
    PHPFPM -->|"Delegates_Audio_Tasks"| MusicSimilarityCont

    %% Class Definitions for Colour Styling
    classDef container fill:#C1E1DC,stroke:#333,stroke-width:2px;
    classDef app fill:#FAD4C0,stroke:#C56,stroke-width:2px;
    classDef config fill:#E6E6FA,stroke:#333,stroke-width:2px;
    classDef external fill:#C0D6F5,stroke:#333,stroke-width:2px;

    %% Click Events
    click Frontend "https://github.com/iammordaty/assistant-web/blob/master/public/index.php"
    click Backend "https://github.com/iammordaty/assistant-web/tree/master/src"
    click Config "https://github.com/iammordaty/assistant-web/blob/master/config/config.inc"
    click AudioProc "https://github.com/iammordaty/assistant-web/tree/master/.docker/php-fpm/bin"
    click MusicClassifierModule "https://github.com/iammordaty/assistant-web/tree/master/src/Assistant/Module/Common/Extension/MusicClassifier"
    click Beatport "https://github.com/iammordaty/assistant-web/blob/master/src/Assistant/Module/Common/Extension/BeatportApiClient.php"
    click PHPFPM "https://github.com/iammordaty/assistant-web/tree/master/.docker/php-fpm"
    click Nginx "https://github.com/iammordaty/assistant-web/tree/master/.docker/nginx"
    click MusicClassifierCont "https://github.com/iammordaty/assistant-web/tree/master/.docker/music-classifier"
    click MusicSimilarityCont "https://github.com/iammordaty/assistant-web/tree/master/.docker/music-similarity"
    click CLI "https://github.com/iammordaty/assistant-web/blob/master/bin/console.php"
    click Compose "https://github.com/iammordaty/assistant-web/blob/master/docker-compose.yml"
```
