# cde90/web-spotify-thing architecture

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

- Interactive diagram: https://gitdiagram.com/cde90/web-spotify-thing
- Repository: https://github.com/cde90/web-spotify-thing

## Overview

##### Project Type and Purpose
- This project is a full-stack web application scaffolded using the T3 Stack. It brings together Next.js (for the frontend and server-side rendering), NextAuth.js (for authentication), Prisma and Drizzle (for database interactions and ORM), Tailwind CSS (for styling), and tRPC (for typesafe API communication).
- The README and file structure indicate that this project is intended as a starter kit; the developer can extend its functionality as needed. It provides endpoints for API interactions, various page components (e.g., dashboard, feed, import, leaderboard), and integrations (e.g., Spotify and upload functionalities).

##### Analyzing the File Structure
- Top-level files and directories such as .env.example, next.config.js, package.json, and tailwind.config.ts suggest configuration and build integrations.
- The “src” directory is the core of the application code:
- src/app: Contains the Next.js app directory, with both UI pages (for dashboard, feed, leaderboard, etc.) and a series of API routes (under src/app/api) such as health checks, db seeding, uploading, and more.
- src/components: Hosts reusable UI components along with a UI library (organized under components/ui and ui-parts).
- src/server: Contains backend logic, including the database schema and integrations (e.g., Spotify integration in src/server/spotify).
- src/lib: Utility modules and helper functions used across the project.
- Build configuration and environment files, GitHub workflows (in .github), and testing configurations which, although not detailed in this tree, are crucial for deployment and code quality.

##### Key Architectural Elements
- Frontend (Client Layer): Build using Next.js and Tailwind CSS, comprising pages, reusable components, and React elements that render the user experience.
- API Layer (Serverless Functions): Built into the Next.js “app/api” directory. This includes endpoints for fetching data (e.g., now playing, recent listens), posting data (uploads, refreshes), and health and DB seeding functionalities.
- Authentication: Integrated via NextAuth.js to manage secure access and user sessions.
- Data Persistence: Managed through Prisma and Drizzle using the server/db modules, representing the database layer. Include components like the schema definition and ORM usage.
- External Integrations: Spotify integration is handled in src/server/spotify and file processing/upload in the uploadthing APIs.
- Utility and Shared Libraries: Under src/lib, these include common utilities and shared functionality for things such as chart rendering and window resize events.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client/Frontend Subgraph
    subgraph "Client/Frontend"
        CF1["Dashboard Page"]:::client
        CF2["Feed Page"]:::client
        CF3["Import Page"]:::client
        CF4["Leaderboard Page"]:::client
        CF5["Reusable UI Components"]:::client
    end

    %% API Endpoints Subgraph
    subgraph "API Endpoints"
        API1["General API Routes"]:::api
        subgraph "Upload API"
            API2["Upload API: Route"]:::api
            API3["Upload API: Core"]:::api
        end
    end

    %% Authentication Subgraph
    subgraph "Authentication"
        AUTH1["Check Auth"]:::auth
        AUTH2["Auth Providers"]:::auth
    end

    %% Database Subgraph
    subgraph "Database"
        DB1["DB Index"]:::db
        DB2["DB Schema"]:::db
        DB3["Drizzle Config"]:::db
    end

    %% External Integrations Subgraph
    subgraph "External Integrations"
        EXT1["Spotify Integration"]:::ext
        EXT2["Spotify Types"]:::ext
    end

    %% Utilities & Shared Libraries Subgraph
    subgraph "Utilities & Shared Libraries"
        UTIL1["Common Utilities"]:::util
    end

    %% Connections
    CF5 -->|"requests"| API1
    API1 -->|"validate"| AUTH1
    API1 -->|"db-ops"| DB1
    API1 -->|"external-calls"| EXT1

    %% Additional intra-group connections (for clarity)
    %% Connect Authentication nodes
    AUTH1 --- AUTH2

    %% Connect Database nodes vertically
    DB1 --- DB2
    DB2 --- DB3

    %% Connect External Integrations nodes
    EXT1 --- EXT2

    %% Click Events for Client/Frontend
    click CF1 "https://github.com/cde90/web-spotify-thing/blob/main/src/app/dashboard/page.tsx"
    click CF2 "https://github.com/cde90/web-spotify-thing/blob/main/src/app/feed/page.tsx"
    click CF3 "https://github.com/cde90/web-spotify-thing/blob/main/src/app/import/page.tsx"
    click CF4 "https://github.com/cde90/web-spotify-thing/blob/main/src/app/leaderboard/page.tsx"
    click CF5 "https://github.com/cde90/web-spotify-thing/tree/main/src/components"

    %% Click Events for API Endpoints
    click API1 "https://github.com/cde90/web-spotify-thing/tree/main/src/app/api"
    click API2 "https://github.com/cde90/web-spotify-thing/blob/main/src/app/api/uploadthing/route.ts"
    click API3 "https://github.com/cde90/web-spotify-thing/blob/main/src/app/api/uploadthing/core.ts"

    %% Click Events for Authentication
    click AUTH1 "https://github.com/cde90/web-spotify-thing/blob/main/src/app/dashboard/check-auth.ts"
    click AUTH2 "https://github.com/cde90/web-spotify-thing/blob/main/src/app/providers.tsx"

    %% Click Events for Database
    click DB1 "https://github.com/cde90/web-spotify-thing/blob/main/src/server/db/index.ts"
    click DB2 "https://github.com/cde90/web-spotify-thing/blob/main/src/server/db/schema.ts"
    click DB3 "https://github.com/cde90/web-spotify-thing/blob/main/drizzle.config.ts"

    %% Click Events for External Integrations
    click EXT1 "https://github.com/cde90/web-spotify-thing/blob/main/src/server/spotify/spotify.ts"
    click EXT2 "https://github.com/cde90/web-spotify-thing/blob/main/src/server/spotify/types.ts"

    %% Click Event for Utilities
    click UTIL1 "https://github.com/cde90/web-spotify-thing/tree/main/src/lib"

    %% Styles
    classDef client fill:#fde2e2,stroke:#d62828,stroke-width:2px
    classDef api fill:#e0f7fa,stroke:#00796b,stroke-width:2px
    classDef auth fill:#e8f5e9,stroke:#2e7d32,stroke-width:2px
    classDef db fill:#fff3e0,stroke:#ef6c00,stroke-width:2px
    classDef ext fill:#f1f8e9,stroke:#558b2f,stroke-width:2px
    classDef util fill:#e3f2fd,stroke:#1565c0,stroke-width:2px
```
