# mdziegielewska/music-genre-classification architecture

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

- Interactive diagram: https://gitdiagram.com/mdziegielewska/music-genre-classification
- Repository: https://github.com/mdziegielewska/music-genre-classification

## Overview

##### Project Type and Purpose
- This is a full-stack web application built with Django (Python) that integrates a pre-trained music genre classification model.
- Users submit audio tracks, the system predicts genre and suggests similar tracks, with optional user registration to save search history.

##### File Structure Analysis
- Top-level:
- app/ – contains both frontend (templates, static) and backend (Django project & app) plus the ML model code.
- Presentation.pptx, README.md.
- Inside app/:
- src/ – Django project (“MGCproject”) and Django app (“MGCapp”) plus predict_genre.py entrypoint.
- src/MGCmodel/ – holds model code (cnn_music_genre_classifier.py, preprocess.py) and artifacts (trainModel.h5, data.json).
- cypress/ – end-to-end tests for the UI.
- Architectural pattern: classic Django MVC:
- Models (MGCapp/models.py), Views (MGCapp/views.py, predict_genre.py), Templates (app/src/templates).
- Static assets (app/src/static).
- Machine learning service embedded alongside backend code.

##### Key Components
a. Web Browser (Client)
– UI rendered via Django templates & served static assets
– Cypress test runner (E2E testing)
b. Django Web Server (Backend)
– URL router (MGCproject/urls.py) → Views (MGCapp/views.py, predict_genre.py)
– Forms & authentication flows (MGCapp/forms.py)
– ORM & Database (Django models → PostgreSQL/SQLite)
c. ML Model Service
– Prediction module (music_genre_classifier.py)
– Preprocessing (preprocess.py)
– Model file (trainModel.h5)
d. Data Store
– User, SongSearchHistory tables (managed by Django migrations)
– Static/media files (uploaded audio or images)
e. External/Deployment (optional)
– CI/CD or containerization if planned

##### Relationships & Data Flow
1. User submits track via Web UI → HTTP POST to Django view.
2. View invokes ML service: preprocess → load model → predict genre.
3. Prediction result returned to view → rendered in HTML → sent to client.
4. If authenticated, save search to database via ORM.
5. User requests “saved history” → view queries database → renders history page.
6. Cypress E2E tests simulate browser interactions and validate flows.

##### Architectural Patterns & Principles
- MVC (Model-View-Controller) with clear separation of concerns.
- “Fat view, thin template”: business logic in views/MGCmodel modules.
- Single-process ML integration; consider decoupling with a microservice in future.
- Use of Django migrations for schema evolution.
- Automated E2E testing layer (Cypress).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Presentation Layer
    subgraph "Presentation Layer"
        direction TB
        Client["Web Browser"]:::frontend
        Templates["UI Templates"]:::frontend
        StaticAssets["Static Assets"]:::frontend
    end

    %% Testing Layer
    subgraph "Testing Layer"
        direction TB
        Cypress["Cypress E2E Tests"]:::test
    end

    %% Application Layer
    subgraph "Application Layer"
        direction TB
        RouterProj["Django URL Router\n(MGCproject/urls.py)"]:::app
        RouterApp["Django URL Router\n(MGCapp/urls.py)"]:::app
        Views["Django Views/Controllers"]:::app
        Entrypoint["Prediction Entrypoint\n(predict_genre.py)"]:::app
        Forms["Forms & Authentication"]:::app
        Models["ORM Models"]:::app
        Migrations["Database Migrations"]:::app
        Settings["Project Settings"]:::app
        Manage["Django Entrypoint\n(manage.py)"]:::app
    end

    %% ML Service
    subgraph "ML Service" 
        direction TB
        Preprocess["Preprocessing Module"]:::ml
        Classifier["Genre Classifier Logic"]:::ml
        ModelArtifact["Trained Model (trainModel.h5)"]:::ml
        ModelMeta["Model Metadata (data.json)"]:::ml
    end

    %% Data Layer
    subgraph "Data Layer"
        direction TB
        DB["Database (PostgreSQL/SQLite)"]:::data
        Media["Static/Media Storage"]:::data
    end

    %% Connections
    Client -->|"HTTP Request (POST/GET)"| RouterProj
    Client -->|"HTTP Request (POST/GET)"| RouterApp
    RouterProj -->|"routes to"| Views
    RouterApp -->|"routes to"| Views
    Views -->|"invokes"| Preprocess
    Preprocess -->|"process audio"| Classifier
    Classifier -->|"loads model"| ModelArtifact
    Classifier -->|"reads config"| ModelMeta
    Classifier -->|"returns prediction"| Views
    Views -->|"ORM Query/Save"| Models
    Views -->|"uses migrations"| Migrations
    Views -->|"handles file upload"| Media
    Views -->|"renders via templates/static"| Templates
    Views -->|"renders via templates/static"| StaticAssets
    Views -->|"HTTP Response"| Client
    Entrypoint -->|"calls Views/ML flow"| Views
    Client -.->|"tested by"| Cypress
    Cypress -->|"simulates browser"| Client

    %% Click Events
    click Templates "https://github.com/mdziegielewska/music-genre-classification/tree/main/app/src/templates/"
    click StaticAssets "https://github.com/mdziegielewska/music-genre-classification/tree/main/app/src/static/"
    click StaticAssets "https://github.com/mdziegielewska/music-genre-classification/tree/main/app/src/static/media/"
    click Cypress "https://github.com/mdziegielewska/music-genre-classification/blob/main/app/cypress/integration/logIn.ts"
    click RouterProj "https://github.com/mdziegielewska/music-genre-classification/blob/main/app/src/MGCproject/urls.py"
    click RouterApp "https://github.com/mdziegielewska/music-genre-classification/blob/main/app/src/MGCapp/urls.py"
    click Views "https://github.com/mdziegielewska/music-genre-classification/blob/main/app/src/MGCapp/views.py"
    click Entrypoint "https://github.com/mdziegielewska/music-genre-classification/blob/main/app/src/predict_genre.py"
    click Forms "https://github.com/mdziegielewska/music-genre-classification/blob/main/app/src/MGCapp/forms.py"
    click Models "https://github.com/mdziegielewska/music-genre-classification/blob/main/app/src/MGCapp/models.py"
    click Migrations "https://github.com/mdziegielewska/music-genre-classification/tree/main/app/src/MGCapp/migrations/"
    click Preprocess "https://github.com/mdziegielewska/music-genre-classification/blob/main/app/src/MGCmodel/preprocess.py"
    click Classifier "https://github.com/mdziegielewska/music-genre-classification/blob/main/app/src/MGCmodel/music_genre_classifier.py"
    click Classifier "https://github.com/mdziegielewska/music-genre-classification/blob/main/app/src/MGCmodel/cnn_music_genre_classifier.py"
    click ModelArtifact "https://github.com/mdziegielewska/music-genre-classification/blob/main/app/src/MGCmodel/trainModel.h5"
    click ModelMeta "https://github.com/mdziegielewska/music-genre-classification/blob/main/app/src/MGCmodel/data.json"
    click Settings "https://github.com/mdziegielewska/music-genre-classification/blob/main/app/src/MGCproject/settings.py"
    click Manage "https://github.com/mdziegielewska/music-genre-classification/blob/main/app/src/manage.py"

    %% Styles
    classDef frontend fill:#ADD8E6,stroke:#000;
    classDef app fill:#90EE90,stroke:#000;
    classDef ml fill:#FFA500,stroke:#000;
    classDef data fill:#D3D3D3,stroke:#000;
    classDef test fill:#DDA0DD,stroke:#000;
```
