# victornivelo/reproductor_mp3 architecture

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

- Interactive diagram: https://gitdiagram.com/victornivelo/reproductor_mp3
- Repository: https://github.com/victornivelo/reproductor_mp3

## Overview

##### Project Type and Purpose
- The project is a desktop music player application written in Python.
- It uses a graphical user interface (GUI) with both a light and dark mode (as seen in the README images and “modo claro” and “modo oscuro” references).
- The application likely manages audio playback, user-configurable settings, statistical tracking, and playlist management using JSON files stored under the “datos” directory.

##### Analyzing the File Structure
- Top-level directories include:
- datos – Contains configuration files, statistics (canciones.json, reproduccion.json), and user playlists (favorito, me_gusta).
- prototipo – Appears to hold a prototype with an HTML based (or web-like) interface and associated prototype scripts. These are likely early or alternative UI experiments.
- src – Contains the actual source code organized by MVC principles:
▪ modelo – Contains classes/models such as “biblioteca.py” and “cancion.py.”
▪ vista – Contains the GUI components (main view in vista_principal.py, and additional reusable components like mini_reproductor and tooltips).
▪ controlador – Contains controllers to handle interactions such as file operations, music library management, button interactions, theme changes, and controlling the playback.
▪ Additionally, a “constantes.py” and a “utiles.py” file are present for shared constants and utility functions.
- The test folder indicates there are unit tests for at least some components (e.g., test/test_constantes.py).
- Build/script files like “requirements.txt” provide a list of dependencies which support the technical stack.

a. Main Components:
- GUI (Vista): Represents the user interface elements. Include:
- Main window (vista_principal.py)
- Sub-components (cola_reproduccion, configuracion, estadisticas, mini_reproductor, etc.)
- Controllers: Located in src/controlador.
- Main controller logic (controlador.py)
- Specialized controllers: handling files, library (biblioteca), playback (reproductor), buttons, and theme configurations.
- Models: Located in src/modelo.
- Music library (biblioteca.py)
- Song objects (cancion.py)
- Data Storage: JSON files within the “datos” folder which store persistent configurations, playback statistics, and playlists.

b. Relationships and Interactions:
- The GUI (view) interacts directly with the controllers. For example, when a user clicks on a play button, the GUI forwards this event to the corresponding controlador_reproductor.
- Controllers mediate between the view and the model: user actions in the view lead to changes in the model (e.g., updating playlists, fetching song data).
- The model then reads/writes data to JSON files located in the “datos” directory to persist configurations and statistics.
- The prototipo folder can be visualized as an experimental or alternate interface layer that may share similar underlying logic but is not the main focus.

c. Architectural Patterns or Design Principles:
- MVC (Model-View-Controller): Separation of interface (vista), business logic (controlador), and data (modelo).
- The project also emphasizes modularity, separating concerns into discrete modules and packages (e.g., different controllers for different functionalities).
- Use of JSON for configuration and data persistence indicates a lightweight approach for data storage rather than a full-blown database.

d. Relevant Technologies and Libraries:
- Python is the main programming language.
- Likely uses GUI frameworks (potentially Tkinter or PyQt, inferred from file names and structure – check “vista” components for specifics).
- The requirements.txt will list the actual dependencies, but it likely includes libraries for GUI development, JSON processing, and possibly multimedia handling.

##### Additional Details to Capture
- Incorporate modularity by identifying each controller’s role (for instance, controlador_biblioteca.py for library management, controlador_reproductor.py for playback).
- Cross-cutting utilities and common functions (like those in src/utiles.py) that support multiple parts of the system.
- Primary entry point (src/principal.py) which likely initializes the application and orchestrates the setup of view, controller, and model.

## Diagram (Mermaid)

```mermaid
graph TD
    %% Application Entry Point
    Entry["Application Entry Point"]:::entry

    %% User Interface (Vista)
    subgraph "User Interface (Vista)"
        UI_Main["Main View (vista_principal.py)"]:::ui
        UI_Cole["Cola Reproduccion (component)"]:::ui
        UI_Conf["Configuracion (component)"]:::ui
        UI_Estad["Estadisticas (component)"]:::ui
        UI_Mini["Mini Reproductor (component)"]:::ui
        UI_Tool["Tooltip (tooltip.py)"]:::ui
    end

    %% Controllers (Controlador)
    subgraph "Controllers (Controlador)"
        C_Main["Main Controller (controlador.py)"]:::controller
        C_Arch["File Controller (controlador_archivos.py)"]:::controller
        C_Bibl["Library Controller (controlador_biblioteca.py)"]:::controller
        C_Bot["Buttons Controller (controlador_botones.py)"]:::controller
        C_Reprod["Playback Controller (controlador_reproductor.py)"]:::controller
        C_Tema["Theme Controller (controlador_tema.py)"]:::controller
    end

    %% Models (Modelo)
    subgraph "Models (Modelo)"
        M_Bibl["Music Library (biblioteca.py)"]:::model
        M_Cancion["Song (cancion.py)"]:::model
    end

    %% Data Storage (JSON Files)
    subgraph "Data Storage (JSON Files)"
        DS_Conf["Config JSON (ajustes.json)"]:::data
        DS_Estad["Stats JSON (canciones.json & reproduccion.json)"]:::data
        DS_Playlist["Playlists JSON (favorito.json & me_gusta.json)"]:::data
    end

    %% Resources (Assets)
    subgraph "Resources (Assets)"
        R_Iconos["Icons (recursos/iconos)"]:::resource
        R_Imagenes["Images (recursos/imagenes)"]:::resource
    end

    %% Prototyping / Alternate Interface
    subgraph "Prototyping / Alternate Interface"
        P_HTML["Prototype View (vista_principal.html)"]:::prototype
        P_Reprod["Prototype Playback (prototipo_reproductor.py)"]:::prototype
    end

    %% Common Utilities
    subgraph "Common Utilities"
        U_Common["Common Utilities (utiles.py)"]:::utility
        U_Vista["View Utilities (utiles in src/vista/utiles)"]:::utility
    end

    %% Connections
    Entry -->|"initializes"| UI_Main
    Entry -->|"initializes"| C_Main
    Entry -->|"initializes"| U_Common

    UI_Main -->|"triggers"| C_Main
    UI_Main -->|"uses"| R_Iconos
    UI_Main -->|"uses"| R_Imagenes
    UI_Main -->|"utilizes"| U_Vista

    C_Main -->|"dispatches_to"| C_Arch
    C_Main -->|"dispatches_to"| C_Bibl
    C_Main -->|"dispatches_to"| C_Bot
    C_Main -->|"dispatches_to"| C_Reprod
    C_Main -->|"dispatches_to"| C_Tema

    C_Bibl -->|"updates"| M_Bibl
    C_Reprod -->|"updates"| M_Cancion

    M_Bibl -->|"persists_to"| DS_Conf
    M_Bibl -->|"persists_to"| DS_Estad
    M_Bibl -->|"persists_to"| DS_Playlist
    M_Cancion -->|"persists_to"| DS_Conf
    M_Cancion -->|"persists_to"| DS_Estad
    M_Cancion -->|"persists_to"| DS_Playlist

    %% Prototyping alternative flow (experimental)
    Entry -->|"alternative_UI"| P_HTML
    P_HTML -->|"controls"| P_Reprod

    %% Click Events
    click Entry "https://github.com/victornivelo/reproductor_mp3/blob/main/src/principal.py"
    click UI_Main "https://github.com/victornivelo/reproductor_mp3/blob/main/src/vista/vista_principal.py"
    click UI_Cole "https://github.com/victornivelo/reproductor_mp3/blob/main/src/vista/componentes/cola_reproduccion.py"
    click UI_Conf "https://github.com/victornivelo/reproductor_mp3/blob/main/src/vista/componentes/configuracion.py"
    click UI_Estad "https://github.com/victornivelo/reproductor_mp3/blob/main/src/vista/componentes/estadisticas.py"
    click UI_Mini "https://github.com/victornivelo/reproductor_mp3/blob/main/src/vista/componentes/mini_reproductor.py"
    click UI_Tool "https://github.com/victornivelo/reproductor_mp3/blob/main/src/vista/tooltip.py"
    click C_Main "https://github.com/victornivelo/reproductor_mp3/blob/main/src/controlador/controlador.py"
    click C_Arch "https://github.com/victornivelo/reproductor_mp3/blob/main/src/controlador/controlador_archivos.py"
    click C_Bibl "https://github.com/victornivelo/reproductor_mp3/blob/main/src/controlador/controlador_biblioteca.py"
    click C_Bot "https://github.com/victornivelo/reproductor_mp3/blob/main/src/controlador/controlador_botones.py"
    click C_Reprod "https://github.com/victornivelo/reproductor_mp3/blob/main/src/controlador/controlador_reproductor.py"
    click C_Tema "https://github.com/victornivelo/reproductor_mp3/blob/main/src/controlador/controlador_tema.py"
    click M_Bibl "https://github.com/victornivelo/reproductor_mp3/blob/main/src/modelo/biblioteca.py"
    click M_Cancion "https://github.com/victornivelo/reproductor_mp3/blob/main/src/modelo/cancion.py"
    click DS_Conf "https://github.com/victornivelo/reproductor_mp3/blob/main/datos/configuracion/ajustes.json"
    click DS_Estad "https://github.com/victornivelo/reproductor_mp3/blob/main/datos/estadisticas/canciones.json"
    click DS_Playlist "https://github.com/victornivelo/reproductor_mp3/blob/main/datos/listas/favorito/favorito.json"
    click R_Iconos "https://github.com/victornivelo/reproductor_mp3/tree/main/recursos/iconos"
    click R_Imagenes "https://github.com/victornivelo/reproductor_mp3/tree/main/recursos/imagenes"
    click P_HTML "https://github.com/victornivelo/reproductor_mp3/blob/main/prototipo/html/vista_principal.html"
    click P_Reprod "https://github.com/victornivelo/reproductor_mp3/blob/main/prototipo/prototipo_reproductor.py"
    click U_Common "https://github.com/victornivelo/reproductor_mp3/blob/main/src/utiles.py"
    click U_Vista "https://github.com/victornivelo/reproductor_mp3/tree/main/src/vista/utiles"

    %% Styles
    classDef entry fill:#ffdd99,stroke:#333,stroke-width:2px;
    classDef ui fill:#c6e2ff,stroke:#333,stroke-width:2px;
    classDef controller fill:#ffcccc,stroke:#333,stroke-width:2px;
    classDef model fill:#d1e7dd,stroke:#333,stroke-width:2px;
    classDef data fill:#fce5cd,stroke:#333,stroke-width:2px;
    classDef resource fill:#e2e2f9,stroke:#333,stroke-width:2px;
    classDef prototype fill:#f9e2e2,stroke:#333,stroke-width:2px;
    classDef utility fill:#d9ead3,stroke:#333,stroke-width:2px;
```
