# dionisiykdo/spotistat-frontend architecture

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

- Interactive diagram: https://gitdiagram.com/dionisiykdo/spotistat-frontend
- Repository: https://github.com/dionisiykdo/spotistat-frontend

## Overview

##### Project Type and Purpose
- This is clearly a frontend web application that provides a rich, interactive UI for displaying Spotify usage statistics.
- The README emphasizes key integration parts: Spotify authentication and data consumption from both Spotify’s API and an extended history export.
- The project is part of a larger ecosystem since it depends on a separate SpotiStat backend.

##### Analyzing the File Structure
- Top-level files like package.json, postcss.config.js, svelte.config.js, and vite.config.js indicate that this is built with modern JavaScript tooling and Svelte for the UI.
- The src directory contains primary application code:
- src/app.html and src/app.css set up the initial HTML structure and styling.
- The src/lib folder holds reusable UI components (e.g., Header, Footer, Sidebar, CardTrackList) and supporting files like authentication (auth.ts), type definitions, and chart styles.
- The src/routes folder is structured with a mix of static and dynamic routes, including dynamic “[accountId]” pages that partition the app by different user accounts. Within this folder are pages for various functionalities:
- Authentication pages under src/routes/auth.
- Pages dedicated to Spotify integrations (recently played, saved tracks, top artists/tracks, tracks by year) and other sections like artists, trends, settings, and import.
- Specialized visualization components (e.g., D3Chart, D3BarChart, D3TimelineChart) are integrated within their respective routes.
- Static assets are available in the static directory.

a. Main Components to Include:
- User Interface (UI) Layer:
- Svelte Application Shell (entry point defined in app.html and app.css).
- Navigation and Layout Components (global +layout.svelte files in src/routes).
- Reusable UI Components (Header, Footer, Sidebar, CardTrackList, etc. from src/lib).
- Visualization Modules (various D3-based Svelte components for charts).
- Routing Layer:
- Dynamic Routing Structure based on the src/routes folder, including dynamic "[accountId]" pages that encapsulate user-specific dashboards and discovery pages (artists, spotify, tracks, trends, etc.).
- Data Integration:
- External Spotify API Integration for real-time statistics.
- Data Loader Modules (load.ts files in various route directories) that fetch or process data.
- Interaction with the SpotiStat backend (as mentioned in the README requirements).

b. Relationships and Interactions:
- That specific UI components (like charts in the trends or artists pages) receive data from their associated load.ts logic.
- An authentication flow from the auth-related route to the data layer demonstrating the usage of authentication tokens or sessions.

c. Architectural Patterns and Design Principles:
- Separation of Concerns: UI components are neatly encapsulated in the lib folder while business logic is embedded in each route’s corresponding data loader (load.ts) files.
- Use of Dynamic Routing: The “[accountId]” dynamic routing pattern indicates a multi-tenant or user-specific design.
- Component Reusability: Many UI elements are designed as reusable Svelte components.

d. Technologies to Highlight:
- Svelte 5 for the reactive UI.
- Tailwind CSS for styling and responsive design.
- D3.js for dynamic and interactive data visualizations.
- Node.js environment (per the package requirements) supporting module bundling and development server usage.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Top-level User
    User["User"]:::ui

    %% UI Layer
    subgraph "UI Layer"
        appShell["Svelte App Shell"]:::ui
        globalLayout["Global Navigation & Layout"]:::ui
        accountLayout["Dynamic Account Layout"]:::ui
        subgraph "Reusable UI Components"
            header["Header Component"]:::ui
            footer["Footer Component"]:::ui
            sidebar["Sidebar Component"]:::ui
            cardTrackList["CardTrackList Component"]:::ui
        end
        authLogic["Authentication Logic"]:::auth
    end

    %% Routes
    subgraph "Routes"
        authPage["Authentication Page"]:::route
        artistsPage["Artists Page"]:::route
        spotifyTracksYearPage["Spotify Tracks by Year Page"]:::route
        tracksPage["Tracks Page"]:::route
        trendsPage["Trends Page"]:::route
    end

    %% Data Loaders & Visualizations
    subgraph "Data Loaders & Visualizations"
        artistsDL["Artists Data Loader"]:::data
        tracksByYearDL["Spotify Tracks by Year Data Loader"]:::data
        tracksDL["Tracks Data Loader"]:::data
        trendsDL["Trends Data Loader"]:::data
        artistsViz["Artists Visualization"]:::viz
        tracksByYearViz["Spotify Tracks by Year Visualization"]:::viz
        trendsBarViz["Trends Visualization (Bar Chart)"]:::viz
        trendsTimelineViz["Trends Visualization (Timeline Chart)"]:::viz
    end

    %% External Services
    subgraph "External Services"
        spotifyAPI["Spotify API"]:::external
        spotistatBackend["SpotiStat Backend"]:::external
    end

    %% Connections
    User --> appShell
    appShell --> globalLayout
    appShell --> accountLayout
    appShell --> header
    appShell --> footer
    appShell --> sidebar
    appShell --> cardTrackList

    globalLayout --> authPage
    accountLayout --> artistsPage
    accountLayout --> spotifyTracksYearPage
    accountLayout --> tracksPage
    accountLayout --> trendsPage

    authPage --> authLogic

    artistsPage --> artistsDL
    artistsDL --> artistsViz

    spotifyTracksYearPage --> tracksByYearDL
    tracksByYearDL --> tracksByYearViz

    tracksPage --> tracksDL

    trendsPage --> trendsDL
    trendsDL --> trendsBarViz
    trendsDL --> trendsTimelineViz

    %% Data Loaders to External Services
    artistsDL -->|"fetch"| spotifyAPI
    artistsDL -->|"integrate"| spotistatBackend

    tracksByYearDL -->|"fetch"| spotifyAPI
    tracksByYearDL -->|"integrate"| spotistatBackend

    tracksDL -->|"fetch"| spotifyAPI
    tracksDL -->|"integrate"| spotistatBackend

    trendsDL -->|"fetch"| spotifyAPI
    trendsDL -->|"integrate"| spotistatBackend

    %% Click Events
    click appShell "https://github.com/dionisiykdo/spotistat-frontend/blob/main/src/app.html"
    click globalLayout "https://github.com/dionisiykdo/spotistat-frontend/blob/main/src/routes/+layout.svelte"
    click accountLayout "https://github.com/dionisiykdo/spotistat-frontend/blob/main/src/routes/[accountId]/+layout.svelte"
    click header "https://github.com/dionisiykdo/spotistat-frontend/blob/main/src/lib/Header.svelte"
    click footer "https://github.com/dionisiykdo/spotistat-frontend/blob/main/src/lib/Footer.svelte"
    click sidebar "https://github.com/dionisiykdo/spotistat-frontend/blob/main/src/lib/Sidebar.svelte"
    click cardTrackList "https://github.com/dionisiykdo/spotistat-frontend/blob/main/src/lib/CardTrackList.svelte"
    click authLogic "https://github.com/dionisiykdo/spotistat-frontend/blob/main/src/lib/auth.ts"
    click authPage "https://github.com/dionisiykdo/spotistat-frontend/blob/main/src/routes/auth/+page.svelte"
    click artistsDL "https://github.com/dionisiykdo/spotistat-frontend/blob/main/src/routes/[accountId]/artists/load.ts"
    click tracksByYearDL "https://github.com/dionisiykdo/spotistat-frontend/blob/main/src/routes/[accountId]/spotify/tracks_by_year/load.ts"
    click tracksDL "https://github.com/dionisiykdo/spotistat-frontend/blob/main/src/routes/[accountId]/tracks/load.ts"
    click trendsDL "https://github.com/dionisiykdo/spotistat-frontend/blob/main/src/routes/[accountId]/trends/load.ts"
    click artistsViz "https://github.com/dionisiykdo/spotistat-frontend/blob/main/src/routes/[accountId]/artists/D3Chart.svelte"
    click tracksByYearViz "https://github.com/dionisiykdo/spotistat-frontend/blob/main/src/routes/[accountId]/spotify/tracks_by_year/D3Chart.svelte"
    click trendsBarViz "https://github.com/dionisiykdo/spotistat-frontend/blob/main/src/routes/[accountId]/trends/D3BarChart.svelte"
    click trendsTimelineViz "https://github.com/dionisiykdo/spotistat-frontend/blob/main/src/routes/[accountId]/trends/D3TimelineChart.svelte"

    %% Styles
    classDef ui fill:#AED581,stroke:#33691E,stroke-width:2px;
    classDef route fill:#FFF176,stroke:#FBC02D,stroke-width:2px;
    classDef data fill:#81D4FA,stroke:#01579B,stroke-width:2px;
    classDef viz fill:#90CAF9,stroke:#0D47A1,stroke-width:2px;
    classDef external fill:#FFAB91,stroke:#D84315,stroke-width:2px;
    classDef auth fill:#CE93D8,stroke:#6A1B9A,stroke-width:2px;
```
