# syeo66/go-shufflify architecture

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

- Interactive diagram: https://gitdiagram.com/syeo66/go-shufflify
- Repository: https://github.com/syeo66/go-shufflify

## Overview

##### Main Components Identification

a) Frontend Layer:
- Static assets (css/, js/, images/)
- Template system (lib/templates/)

b) Application Layer:
- Divide into these main modules:
- Routes Handler (routes/)
- Data Services (data/)
- Library Utilities (lib/)
- Type Definitions (types/)

c) External Services:
- Spotify Web API (right side)
- SQLite Database (left side)

##### Component Relationships

a) User Flow:
- User → Frontend → Routes
- Authentication flow through /login → Spotify OAuth
- Session management between components

b) Data Flow:
- Routes → Data Services → Spotify API
- Data Services → SQLite Database
- Cache interactions (data/cache.go)

##### Specific Implementation Details

Create sections showing:

a) Authentication & Session Management:
- Flow from login through OAuth
- Session store implementation
- Token refresh mechanism

b) Queue Management System:
- Playlist retrieval
- Queue manipulation
- Shuffle functionality

##### Technical Specifications

Use these visual elements:

- Green connections for successful flows
- Red for error handling paths
- Yellow for external service connections

**[Frontend Layer]**
- ↓ ↑
**[Routes Layer]**
- ↓ ↑
**[Data Services Layer] ←→ [Spotify API]**
- ↓ ↑
**[Library Layer] ←→ [SQLite DB]**

##### Important Elements to Highlight

- Session management system
- Token refresh mechanism
- Queue management flow
- Cache implementation
- Template rendering system

##### Component Details

For each major component, include:

a) Routes Layer:
- Authentication endpoints
- Player controls
- Queue management

b) Data Services:
- Spotify API interactions
- Cache management
- Queue operations
- User management

c) Library Utilities:
- Database initialization
- Template preparation
- Session handling
- Environment configuration

##### Technical Stack Indicators

- Go (1.22.5+)
- SQLite
- HTMX
- Spotify Web API
- Gorilla Sessions

## Diagram (Mermaid)

```mermaid
graph TB
    subgraph Frontend
        StaticAssets["Static Assets"]
        Templates["Template System"]
        CSS["CSS Files"]:::file
        JS["JavaScript Files"]:::file
        Images["Images"]:::dir
    end

    subgraph Routes
        Auth["Authentication Routes"]:::routes
        Player["Player Routes"]:::routes
        QueueRoutes["Queue Routes"]:::routes
        RootRoute["Root Routes"]:::routes
    end

    subgraph DataServices
        Cache["Cache System"]:::data
        TokenMgmt["Token Management"]:::data
        QueueMgmt["Queue Management"]:::data
        PlayerMgmt["Player Management"]:::data
        PlaylistMgmt["Playlist Management"]:::data
        UserMgmt["User Management"]:::data
    end

    subgraph Library
        SessionStore["Session Store"]:::lib
        DbInit["Database Init"]:::lib
        TemplateMgmt["Template Management"]:::lib
        EnvConfig["Environment Config"]:::lib
    end

    subgraph External
        SpotifyAPI["Spotify Web API"]
        DB[(SQLite Database)]
    end

    %% Frontend Relationships
    StaticAssets --> CSS
    StaticAssets --> JS
    StaticAssets --> Images
    Templates --> Auth
    Templates --> Player
    Templates --> QueueRoutes

    %% Route Relationships
    Auth --> TokenMgmt
    Player --> PlayerMgmt
    QueueRoutes --> QueueMgmt
    RootRoute --> UserMgmt

    %% Data Service Relationships
    TokenMgmt --> SpotifyAPI
    QueueMgmt --> SpotifyAPI
    PlayerMgmt --> SpotifyAPI
    PlaylistMgmt --> SpotifyAPI
    UserMgmt --> DB
    Cache --> DB

    %% Library Relationships
    SessionStore --> DB
    DbInit --> DB
    TemplateMgmt --> Templates
    EnvConfig --> DataServices

    %% Styling
    classDef routes fill:#f96
    classDef data fill:#9cf
    classDef lib fill:#fcf
    classDef file fill:#cfc
    classDef dir fill:#fcc

    %% Click Events
    click CSS "https://github.com/syeo66/go-shufflify/blob/main/css/styles.css"
    click JS "https://github.com/syeo66/go-shufflify/blob/main/js/htmx.org@2.0.4.js"
    click Images "https://github.com/syeo66/go-shufflify/tree/main/images/"
    click Templates "https://github.com/syeo66/go-shufflify/tree/main/lib/templates"
    click Auth "https://github.com/syeo66/go-shufflify/tree/main/routes"
    click Player "https://github.com/syeo66/go-shufflify/blob/main/routes/getPlayer.go"
    click QueueRoutes "https://github.com/syeo66/go-shufflify/blob/main/routes/getQueue.go"
    click RootRoute "https://github.com/syeo66/go-shufflify/blob/main/routes/getRoot.go"
    click Cache "https://github.com/syeo66/go-shufflify/blob/main/data/cache.go"
    click TokenMgmt "https://github.com/syeo66/go-shufflify/blob/main/data/retrieveToken.go"
    click QueueMgmt "https://github.com/syeo66/go-shufflify/blob/main/data/retrieveQueue.go"
    click PlayerMgmt "https://github.com/syeo66/go-shufflify/blob/main/data/retrievePlayer.go"
    click PlaylistMgmt "https://github.com/syeo66/go-shufflify/blob/main/data/retrievePlaylists.go"
    click UserMgmt "https://github.com/syeo66/go-shufflify/blob/main/data/retrieveUser.go"
    click SessionStore "https://github.com/syeo66/go-shufflify/blob/main/lib/sessionStore.go"
    click DbInit "https://github.com/syeo66/go-shufflify/blob/main/lib/initDb.go"
    click TemplateMgmt "https://github.com/syeo66/go-shufflify/blob/main/lib/prepareTemplates.go"
    click EnvConfig "https://github.com/syeo66/go-shufflify/blob/main/lib/getEnv.go"
```
