# yooooomi/your_spotify architecture

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

- Interactive diagram: https://gitdiagram.com/yooooomi/your_spotify
- Repository: https://github.com/yooooomi/your_spotify

## Overview

##### Project Type & Overall Purpose
- YourSpotify is a full-stack, self-hosted application meant to track a user’s Spotify listening habits. Its primary function is to poll the Spotify API on the backend and provide a rich, componentized frontend dashboard (built in React/TypeScript) to view and analyze user statistics.
- The project is divided into two main applications: the client (in apps/client) and the server (in apps/server), with external integrations (Spotify API, MongoDB, etc.), and uses Docker for containerized deployment.

##### Analyzing the File Tree
- Top-level directories include project configuration files (Dockerfiles, docker-compose, CI configurations) along with the “apps” folder that contains:
a. apps/client: Contains the entire web client application.
- A detailed structure with React components (organized in folders such as src/components, src/scenes) that follow a component-based architecture.
- State management with Redux and utility services.
b. apps/server: Contains the backend code mostly written in TypeScript.
- Includes API endpoints (in routes), database modules (queries, schemas) for MongoDB, authentication (OAuth flow for Spotify), middleware, and various utility tools.
- Additional development-specific code (e.g., apps/dev) and CI/CD settings (.github) are also present.

##### Key Components
a. Frontend (Client):
- React-based user interface which contains multiple UI components and scenes (e.g., dashboards, settings pages, stats views).
- That it interacts with the backend using API calls.
b. Backend (Server):
- The server exposes RESTful endpoints for authentication, data retrieval, importing history, and dashboard stats.
- It includes modules related to OAuth login with Spotify, query modules interacting with MongoDB, and background tasks for polling Spotify.
c. Database:
- MongoDB is used as the datastore (as configured in docker-compose). Label it clearly to show how the server reads/writes user data and statistical information.
d. External Services:
- Spotify API: The server periodically polls and imports data while handling OAuth callbacks.
- (Optionally) GitHub Actions/CI pipelines might be depicted as part of the deployment pipeline if needed.

##### Relationships & Data Flow
- The client’s API calls (HTTP/HTTPS) flowing from the frontend to the server.
- The server querying or updating the MongoDB database.
- The server’s backend processes polling or interacting with the Spotify API.
- Dependencies where the server container relies on the MongoDB container and where the client and server environment variables (API_ENDPOINT, CLIENT_ENDPOINT) are set.
- Docker as the container orchestration layer with separate containers for the server, client, and database.

##### Architectural Patterns & Technologies
- Mention that the server follows a modular structure (using routes, middleware, and services) that supports extensibility. The client uses a component-based architecture with modular styling and state management.
- Deployment details such as Dockerfiles for both client and server, along with CI/CD integration via GitHub workflows.

## Diagram (Mermaid)

```mermaid
graph TD
    %% Container Orchestration (Docker)
    subgraph "Container Orchestration (Docker)"
        Client("Client Application"):::frontend
        Server("Server Application"):::backend
        Mongo("MongoDB"):::database
    end

    %% External Services
    SpotifyAPI("Spotify API"):::external

    %% Backend Modules
    subgraph "Backend Modules"
        APIEndpoints("API Endpoints"):::backend
        OAuthTools("OAuth Tools"):::backend
        DatabaseModules("Database Modules"):::backend
        SpotifyIntegration("Spotify Integration"):::backend
        SpotifyLooper("Spotify Looper"):::backend
    end

    %% Deployment & CI/CD
    subgraph "Deployment & CI/CD"
        DockerfileClient("Dockerfile Client"):::deployment
        DockerfileServer("Dockerfile Server"):::deployment
        DockerCompose("Docker Compose"):::deployment
        CICD("CI/CD Pipelines"):::deployment
    end

    %% Data Flow Connections
    Client -->|"HTTPcalls"| Server
    Server -->|"Queries/Updates"| Mongo

    %% Server Internal Module Connections
    Server -->|"exposes"| APIEndpoints
    Server -->|"handles"| OAuthTools
    Server -->|"uses"| DatabaseModules
    Server -->|"polls"| SpotifyIntegration
    Server -->|"worker"| SpotifyLooper

    %% External API Integration
    SpotifyIntegration -->|"calls"| SpotifyAPI

    %% Deployment Connections
    DockerfileClient -->|"builds"| Client
    DockerfileServer -->|"builds"| Server
    CICD -->|"deploys"| DockerCompose
    DockerCompose -->|"orchestrates"| Client
    DockerCompose -->|"orchestrates"| Server
    DockerCompose -->|"orchestrates"| Mongo

    %% Click Events
    click Client "https://github.com/yooooomi/your_spotify/tree/master/apps/client"
    click Server "https://github.com/yooooomi/your_spotify/tree/master/apps/server"
    click APIEndpoints "https://github.com/yooooomi/your_spotify/tree/master/apps/server/src/routes"
    click OAuthTools "https://github.com/yooooomi/your_spotify/tree/master/apps/server/src/tools/oauth"
    click DatabaseModules "https://github.com/yooooomi/your_spotify/tree/master/apps/server/src/database"
    click SpotifyIntegration "https://github.com/yooooomi/your_spotify/blob/master/apps/server/src/tools/apis/spotifyApi.ts"
    click SpotifyLooper "https://github.com/yooooomi/your_spotify/blob/master/apps/server/src/spotify/looper.ts"
    click DockerfileClient "https://github.com/yooooomi/your_spotify/blob/master/Dockerfile.client"
    click DockerfileServer "https://github.com/yooooomi/your_spotify/blob/master/Dockerfile.server"
    click DockerCompose "https://github.com/yooooomi/your_spotify/blob/master/docker-compose-dev.yml"
    click CICD "https://github.com/yooooomi/your_spotify/tree/master/.github/workflows"

    %% Styling
    classDef frontend fill:#ffcc00,stroke:#333,stroke-width:2px;
    classDef backend fill:#99ccff,stroke:#333,stroke-width:2px;
    classDef database fill:#ccffcc,stroke:#333,stroke-width:2px;
    classDef external fill:#ff9966,stroke:#333,stroke-width:2px;
    classDef deployment fill:#eeeeff,stroke:#333,stroke-width:2px;
```
