# floriande/little-gitster-girl architecture

> Architecture diagram of the GitHub repository floriande/little-gitster-girl, 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/floriande/little-gitster-girl
- Repository: https://github.com/floriande/little-gitster-girl

## Overview

##### Main Components
- User Interface (Frontend):
– Components: All the individual reusable UI elements in src/components such as Navbar, PlayPauseButton, SpotifyLoginButton, Equalizer, etc.
– Routes/Pages: Represent the different screens found in src/routes (for example, the game route, error screens, home page, and other interactive pages).
- Authentication Module:
– Authentication Logic: The Spotify authentication context, provider, and hooks located in src/auth. Highlight that the project uses Spotify’s PKCE flow.
- State Management and Context Providers:
– Contexts: Modules like SpotifyWebPlayerContext and Toast context in src/context, which handle global states.
- i18n (Internationalization):
– Providers and Context: The translation context and translation provider in src/i18n for handling multilingual support.
- Services Layer:
– Business Logic: This includes helper utilities like spotify-helper.ts, playlist PDF generation service, and error handling (Sentry integration).
- Background Workers:
– PDF Generation Worker: Identify the worker process (src/worker/pdf-generation-worker) which handles the generation of playing cards as PDFs.
- Configuration & Build Tools:
– Development and Build Settings: Highlight configuration directories and files (e.g., config/vite-plugins, vite.config.ts, package.json) that set up toolchains and build pipelines.
- External Integrations:
– Spotify API: Mark the external dependency for Spotify authentication and playlist access.
– Sentry/Error Logging: Include error tracking service where applicable.

##### Relationships and Interactions
- Upon authentication, the SpotifyAuthProvider and useSpotifyAuth hook manage token exchange and interactions with the Spotify API.
- The Services layer acts as a mediator between the UI and background processes. For instance, when a user chooses to generate custom playing cards, the request flows from a service method in src/services/playlist-pdf-generator.ts to the PDF generation worker.
- How the PDF generation worker offloads heavy tasks to a separate thread and then returns the output back to the main service module.
- That configuration files and Vite plugins ensure that the development environment supports features such as HTTPS for development, PWA functionality, and self-signed certificate handling.

##### Architectural Patterns
- Context API for global state management: Emphasize how the contexts (for Spotify playback and toast notifications) are used across the application.
- Modular Service Layer: Showcase the service modules which keep external API logic and other processing separate from UI concerns.
- Utilization of Web Workers: The PDF generation worker is an architectural design decision that offloads intensive tasks from the main thread.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Top-level Actor
    U["User Interaction"]:::external

    %% UI Layer
    subgraph "UI Layer"
        UI["UI Components"]:::ui
        R["Routes/Pages"]:::ui
    end

    %% i18n Module
    I18n["i18n Module"]:::i18n

    %% Authentication Module
    Auth["Authentication Module"]:::auth

    %% Global State Providers
    subgraph "Global State Providers"
        SWPC["Spotify WebPlayer Context"]:::context
        Toast["Toast Context"]:::context
    end

    %% Services Layer
    subgraph "Services Layer"
        SH["Spotify Helper"]:::service
        PPDF["Playlist PDF Generator"]:::service
        EHS["Error Handling Service"]:::service
    end

    %% PDF Generation Worker
    Worker["PDF Generation Worker"]:::worker

    %% Configuration & Build Tools
    subgraph "Configuration & Build Tools"
        Vite["Vite Config"]:::config
        VPlugins["Vite Plugins"]:::config
    end

    %% External Integrations
    subgraph "External Integrations"
        SpotifyAPI["Spotify API"]:::external
        Sentry["Sentry External"]:::external
    end

    %% Connections
    U -->|"interacts"| UI
    U -->|"navigates"| R

    UI -->|"triggersAuthentication"| Auth
    UI -->|"accessesState"| SWPC
    UI -->|"accessesState"| Toast
    I18n -->|"providesTranslations"| UI
    Auth -->|"performsPKCE"| SpotifyAPI
    UI -->|"initiatePDFGeneration"| PPDF
    PPDF -->|"offloadsTask"| Worker
    Worker -->|"returnsPDF"| PPDF
    SH -->|"communicatesWith"| SpotifyAPI
    EHS -->|"reportsErrors"| Sentry
    Vite -->|"configures"| UI
    VPlugins -->|"configuresPDFService"| PPDF
    VPlugins -->|"configuresHelper"| SH
    SWPC -->|"feedsStateTo"| UI
    Toast -->|"feedsStateTo"| UI
    Auth -->|"updatesAuthState"| SWPC

    %% Click Events
    click UI "https://github.com/floriande/little-gitster-girl/tree/main/src/components"
    click R "https://github.com/floriande/little-gitster-girl/tree/main/src/routes"
    click Auth "https://github.com/floriande/little-gitster-girl/tree/main/src/auth"
    click SWPC "https://github.com/floriande/little-gitster-girl/tree/main/src/context/SpotifyWebPlayerContext"
    click Toast "https://github.com/floriande/little-gitster-girl/tree/main/src/context/Toast"
    click I18n "https://github.com/floriande/little-gitster-girl/tree/main/src/i18n"
    click SH "https://github.com/floriande/little-gitster-girl/blob/main/src/services/spotify-helper.ts"
    click PPDF "https://github.com/floriande/little-gitster-girl/blob/main/src/services/playlist-pdf-generator.ts"
    click EHS "https://github.com/floriande/little-gitster-girl/blob/main/src/services/sentry-service.ts"
    click Worker "https://github.com/floriande/little-gitster-girl/tree/main/src/worker/pdf-generation-worker"
    click Vite "https://github.com/floriande/little-gitster-girl/blob/main/vite.config.ts"
    click VPlugins "https://github.com/floriande/little-gitster-girl/tree/main/config/vite-plugins"

    %% Styles
    classDef ui fill:#a1cfff,stroke:#1f78b4,stroke-width:2px;
    classDef auth fill:#ffcccb,stroke:#e31a1c,stroke-width:2px;
    classDef context fill:#ffeb9c,stroke:#f1c232,stroke-width:2px;
    classDef i18n fill:#f9cb9c,stroke:#e69138,stroke-width:2px;
    classDef service fill:#b6d7a8,stroke:#6aa84f,stroke-width:2px;
    classDef worker fill:#d9d2e9,stroke:#8e7cc3,stroke-width:2px;
    classDef config fill:#ead1dc,stroke:#b4a7d6,stroke-width:2px;
    classDef external fill:#f4b183,stroke:#d9762e,stroke-width:2px;
```
