# varospaxo/spotilytics architecture

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

- Interactive diagram: https://gitdiagram.com/varospaxo/spotilytics
- Repository: https://github.com/varospaxo/spotilytics

## Overview

##### Project Type and Purpose
- Spotilytics is a desktop application that analyzes offline Spotify data. Unlike applications that fetch data via the Spotify API, it processes data from a downloaded zip file (from Spotify’s privacy settings).
- The tool supports multiple interfaces: several GUIs (for yearly and extended streaming history), a CLI, an HTML output variant, and a PDF export functionality.

##### File Structure
- Notice that all files reside in the project’s root directory. Each Python file corresponds to a different mode of interaction:
- Extended.py: Handles the “Extended Streaming History” GUI.
- Interface.py: Deals with the “Yearly Streaming History” GUI.
- Grand.py: Implements a CLI mode.
- Flask.py: Provides a CLI mode with HTML output.
- spotilytics.py: Contains functionality (or acts as the entry point) that enables PDF exporting of the data.
- The presence of requirements.txt confirms external dependencies, while the .gitignore hints at standard project practices.

##### Core Components and Their Interactions
a. User Interface (UI) Components:
- Multiple interfaces allow the user to interact with the tool:
- GUIs for both yearly and extended histories (Interface.py and Extended.py).
- A Command Line Interface (CLI) provided by Grand.py.
- An HTML output variant via Flask.py.
- A PDF export function offered through spotilytics.py.
b. Data Ingestion and Parsing:
- The core functionality expects a downloaded Spotify zip file. The process starts here—with user input (file selection) and a subsequent extraction/parsing of the data.
c. Analytics and Processing Engine:
- This layer computes various streaming metrics: total playtime, most active hour, top tracks, artists, and search queries.
d. Output Generation:
- Results are then presented through various outputs: interactive GUIs, CLI outputs, HTML displays, or exported PDF documents.

1. Input Layer:
- “User Input” where users provide the Spotify zip file and number of results.
2. Data Extraction/Parsing Component:
- Responsible for unzipping and extracting the needed data.
3. Analytics Engine:
- Processes the extracted data for metrics and insight calculation.
4. Presentation/Output Layer:
- Contains separate nodes for each interface:
- GUI (Interface.py for yearly and Extended.py for extended history).
- CLI (Grand.py) and CLI with HTML output (Flask.py).
- PDF Export module (spotilytics.py).
- From “User Input” to “Data Extraction,” then to “Analytics Engine,” and finally to the respective UI/output components.

##### Address Architectural Patterns
- The design loosely follows layered architecture:
- Presentation Layer (different UIs),
- Business Logic Layer (data extraction and analytics held within the various Python scripts),
- Utility/Output Layer (PDF and HTML generation).
- Modularity: Each interface function (GUI or CLI mode) acts as an independent entry point that leverages common processing functions.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Input Layer
    subgraph "Input Layer"
        A["User Input (Spotify Zip)"]:::input
    end

    %% Processing Layer
    subgraph "Processing Layer"
        B["Data Extraction & Parsing"]:::process
        C["Analytics Engine"]:::process
    end

    %% Presentation/Output Layer
    subgraph "Presentation/Output Layer"
        D["Interface.py (Yearly Streaming GUI)"]:::gui
        E["Extended.py (Extended Streaming GUI)"]:::gui
        F["Grand.py (Command Line Interface)"]:::cli
        G["Flask.py (HTML Output Variant)"]:::cli
        H["spotilytics.py (PDF Export)"]:::pdf
    end

    %% Project Setup
    subgraph "Project Setup"
        I["requirements.txt"]:::setup
        J[".gitignore"]:::setup
    end

    %% Data Flow Connections
    A --> B
    B --> C
    C --> D
    C --> E
    C --> F
    C --> G
    C --> H

    %% Styles
    classDef input fill:#ffe6e6,stroke:#cc0000,stroke-width:2px;
    classDef process fill:#e6f2ff,stroke:#0066cc,stroke-width:2px;
    classDef gui fill:#e6ffe6,stroke:#009933,stroke-width:2px;
    classDef cli fill:#fff5e6,stroke:#ff6600,stroke-width:2px;
    classDef pdf fill:#f0e6ff,stroke:#9933ff,stroke-width:2px;
    classDef setup fill:#f2f2f2,stroke:#999999,stroke-width:2px;

    %% Click Events for Component Mapping
    click D "https://github.com/varospaxo/spotilytics/blob/main/Interface.py"
    click E "https://github.com/varospaxo/spotilytics/blob/main/Extended.py"
    click F "https://github.com/varospaxo/spotilytics/blob/main/Grand.py"
    click G "https://github.com/varospaxo/spotilytics/blob/main/Flask.py"
    click H "https://github.com/varospaxo/spotilytics/blob/main/spotilytics.py"
    click I "https://github.com/varospaxo/spotilytics/blob/main/requirements.txt"
    click J "https://github.com/varospaxo/spotilytics/blob/main/.gitignore"
```
