# mardotquis/spotify-laravel architecture

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

- Interactive diagram: https://gitdiagram.com/mardotquis/spotify-laravel
- Repository: https://github.com/mardotquis/spotify-laravel

## Overview

##### Project type and purpose
- This is a full-stack Laravel web application whose purpose is to sync a user’s Spotify “Liked Songs” into a local database and display them via a clean Blade-powered web UI. It also supports manual or scheduled syncs via a CLI command.

##### Main components
A. Client / Presentation Layer
- Web Browser (or any HTTP client)
- Static assets served from public/ (CSS, JS, images)
B. Web Server & Entry Point
- Nginx/Apache or built-in PHP server (public/index.php → bootstrap/app.php → HTTP Kernel)
C. Laravel Application Layers
1. Routes (routes/web.php)
2. Controllers (app/Http/Controllers/SpotifyController.php)
3. Services (app/Services/SpotifyService.php) – contains business logic and orchestrates API calls and DB writes
4. Models (app/Models/SpotifyTrack.php, SyncHistory.php, User.php) – Eloquent ORM mapping
5. Views (resources/views/*.blade.php) – Blade templates to render HTML
D. Database & Storage
- Relational database (MySQL, Postgres, etc.) with three key tables: users, spotify_tracks, sync_histories
- Optional: file cache/queue tables (jobs, cache) if using queue or file cache drivers
- Storage for user-uploaded or service-generated files (storage/app/public, storage/*)
E. Background / Scheduled Tasks
- artisan command SyncSpotifyLikedTracks (app/Console/Commands)
- Laravel scheduler (Kernel.php → schedule the command)
- Optional: queue workers (config/queue.php, jobs table)
F. External Services
- Spotify Web API (OAuth authentication, data fetch)
- Optional: Email service, third-party logging or analytics (config/mail, config/logging)
G. Deployment & Infrastructure (optional, but useful)
- Docker Compose (PHP-FPM, Nginx, MySQL)
- Serverless stack (AWS Lambda + API Gateway + Aurora Serverless + EventBridge)

##### Relationships and data flows
- User clicks “Connect to Spotify” → Browser → Web Server → Routes → SpotifyController → SpotifyService → External Spotify API → callback → Controller → View → Browser
- User clicks “Sync Now” → same flow as above for manual sync
- Scheduled cron → artisan command → SpotifyService → External API → Database → logs / SyncHistory
- Database reads for page load (Controller → Model → DB → Controller → View)
- If using queues: Controller/Command dispatches a job → Queue Worker pulls job → SpotifyService → DB

##### Architectural patterns & principles
- MVC: clear separation of concerns between Models, Views, Controllers
- Service Layer: business logic extracted into app/Services
- Dependency Injection (in controllers, commands)
- Single Responsibility: each class has one purpose (Controller handles HTTP, Service handles API logic, Model handles DB)
- Scheduler/CLI: reusable commands for both manual and automated tasks
- Config-driven: environment variables, config/*.php for service credentials, queue, cache

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Layer
    Browser["Web Browser"]:::client
    StaticAssets["Static Assets"]:::client
    click StaticAssets "https://github.com/mardotquis/spotify-laravel/tree/main/public/"
    click CSS "https://github.com/mardotquis/spotify-laravel/blob/main/resources/css/app.css"
    click JS "https://github.com/mardotquis/spotify-laravel/blob/main/resources/js/app.js"
    CSS["app.css"]
    JS["app.js"]
    click LayoutView "https://github.com/mardotquis/spotify-laravel/blob/main/resources/views/layouts/app.blade.php"
    click SpotifyView "https://github.com/mardotquis/spotify-laravel/blob/main/resources/views/spotify/index.blade.php"
    LayoutView["layouts/app.blade.php"]
    SpotifyView["spotify/index.blade.php"]

    Browser -->|"HTTP GET/POST"| WebServer
    StaticAssets --> WebServer

    %% Web Server & Entry Point
    WebServer["Web Server\n(public/index.php → bootstrap/app.php)"]:::appComp
    click Entry "https://github.com/mardotquis/spotify-laravel/blob/main/public/index.php"
    click Bootstrap "https://github.com/mardotquis/spotify-laravel/blob/main/bootstrap/app.php"

    WebServer --> LaravelApp

    %% Laravel Application Boundary
    subgraph "Laravel Application"
        direction TB

        %% Routes
        subgraph "Routes" 
            HTTPRoutes["routes/web.php"]:::appComp
            ConsoleRoutes["routes/console.php"]:::appComp
            click HTTPRoutes "https://github.com/mardotquis/spotify-laravel/blob/main/routes/web.php"
            click ConsoleRoutes "https://github.com/mardotquis/spotify-laravel/blob/main/routes/console.php"
        end

        %% Controllers
        subgraph "Controllers"
            BaseController["app/Http/Controllers/Controller.php"]:::appComp
            SpotifyController["app/Http/Controllers/SpotifyController.php"]:::appComp
            click BaseController "https://github.com/mardotquis/spotify-laravel/blob/main/app/Http/Controllers/Controller.php"
            click SpotifyController "https://github.com/mardotquis/spotify-laravel/blob/main/app/Http/Controllers/SpotifyController.php"
        end

        %% Services
        SpotifyService["app/Services/SpotifyService.php"]:::appComp
        click SpotifyService "https://github.com/mardotquis/spotify-laravel/blob/main/app/Services/SpotifyService.php"

        %% Models
        subgraph "Models"
            UserModel["app/Models/User.php"]:::appComp
            TrackModel["app/Models/SpotifyTrack.php"]:::appComp
            SyncModel["app/Models/SyncHistory.php"]:::appComp
            click UserModel "https://github.com/mardotquis/spotify-laravel/blob/main/app/Models/User.php"
            click TrackModel "https://github.com/mardotquis/spotify-laravel/blob/main/app/Models/SpotifyTrack.php"
            click SyncModel "https://github.com/mardotquis/spotify-laravel/blob/main/app/Models/SyncHistory.php"
        end

        %% Views
        subgraph "Views"
            WelcomeView["resources/views/welcome.blade.php"]:::appComp
            LayoutView
            SpotifyView
            click WelcomeView "https://github.com/mardotquis/spotify-laravel/blob/main/resources/views/welcome.blade.php"
        end

        %% Relationships inside Laravel App
        HTTPRoutes -->|routes request| SpotifyController
        SpotifyController -->|calls| SpotifyService
        SpotifyService -->|uses| UserModel
        SpotifyService -->|uses| TrackModel
        SpotifyService -->|uses| SyncModel
        SpotifyController -->|renders| WelcomeView
        SpotifyController -->|renders| SpotifyView
    end

    %% Database
    Database["Relational Database\n(MySQL/Postgres)"]:::db
    click MigrationUsers "https://github.com/mardotquis/spotify-laravel/blob/main/database/migrations/0001_01_01_000000_create_users_table.php"
    click MigrationTracks "https://github.com/mardotquis/spotify-laravel/blob/main/database/migrations/2025_03_02_213639_create_spotify_tracks_table.php"
    click MigrationSyncs "https://github.com/mardotquis/spotify-laravel/blob/main/database/migrations/2025_03_02_213639_create_sync_histories_table.php"
    click MigrationCache "https://github.com/mardotquis/spotify-laravel/blob/main/database/migrations/0001_01_01_000001_create_cache_table.php"
    click MigrationJobs "https://github.com/mardotquis/spotify-laravel/blob/main/database/migrations/0001_01_01_000002_create_jobs_table.php"
    MigrationUsers["create_users_table.php"]
    MigrationTracks["create_spotify_tracks_table.php"]
    MigrationSyncs["create_sync_histories_table.php"]
    MigrationCache["create_cache_table.php"]
    MigrationJobs["create_jobs_table.php"]

    UserModel -->|SQL queries| Database
    TrackModel -->|SQL queries| Database
    SyncModel -->|SQL queries| Database

    %% Scheduler & Background Tasks
    Scheduler["Cron Scheduler"]:::background
    Command["SyncSpotifyLikedTracks\n(app/Console/Commands)"]:::background
    click Command "https://github.com/mardotquis/spotify-laravel/blob/main/app/Console/Commands/SyncSpotifyLikedTracks.php"
    click Kernel "https://github.com/mardotquis/spotify-laravel/blob/main/app/Console/Kernel.php"
    Kernel["app/Console/Kernel.php"]

    Scheduler -->|cron trigger| Kernel
    Kernel -->|schedules| Command
    Command -->|calls| SpotifyService

    %% Queue Worker
    QueueWorker["Queue Worker"]:::background
    click QueueConfig "https://github.com/mardotquis/spotify-laravel/blob/main/config/queue.php"
    QueueConfig["config/queue.php"]
    Command -->|dispatch job| QueueWorker
    QueueWorker -->|process job| SpotifyService
    QueueWorker -->|uses| Database

    %% External Services
    SpotifyAPI["Spotify Web API"]:::external
    click ServicesConfig "https://github.com/mardotquis/spotify-laravel/blob/main/config/services.php"
    ServicesConfig["config/services.php"]
    SpotifyService -->|OAuth/API calls| SpotifyAPI
    SpotifyAPI -->|JSON response| SpotifyService

    %% Storage & Logs
    Storage["Storage & Cache"]:::db
    click PublicDisk "https://github.com/mardotquis/spotify-laravel/tree/main/storage/app/public"
    click FrameworkStorage "https://github.com/mardotquis/spotify-laravel/tree/main/storage/framework/"
    click Logs "https://github.com/mardotquis/spotify-laravel/tree/main/storage/logs"
    PublicDisk["Public Disk"]
    FrameworkStorage["framework"]
    Logs["logs"]

    SpotifyService -->|file writes| Storage

    %% Deployment & Infra
    Docker["Docker Compose"]:::external
    click Docker "https://github.com/mardotquis/spotify-laravel/blob/main/docker-compose.yml"
    Serverless["Serverless Config"]:::external
    click Serverless "https://github.com/mardotquis/spotify-laravel/blob/main/serverless.yml"

    Database --> Docker
    WebServer --> Docker
    LaravelApp --> Docker
    Scheduler --> Serverless

    %% Styles
    classDef appComp fill:#D6E4F0,stroke:#2196F3;
    classDef db fill:#E8F5E9,stroke:#43A047;
    classDef external fill:#FFF3E0,stroke:#FB8C00;
    classDef background fill:#F3E5F5,stroke:#8E24AA;
    classDef client fill:#E3F2FD,stroke:#1E88E5;
```
