# front-end-bootcamp-plus-4/jackpot_plug architecture

> Architecture diagram of the GitHub repository front-end-bootcamp-plus-4/jackpot_plug, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/front-end-bootcamp-plus-4/jackpot_plug
- Repository: https://github.com/front-end-bootcamp-plus-4/jackpot_plug

## Overview

##### Project type and purpose
- This is a full-stack web application built with Next.js and TypeScript, following a 4-layer Clean Architecture (app/api → application/usecases → domain → infra).
- Purpose: Allow users to extract music tracks from long YouTube videos, select favorites, assemble custom playlists, save/play them, and integrate with Spotify/YouTube APIs for search and recommendations. User management is backed by Supabase.

##### File structure
- `app/` — Next.js front-end pages, shared components (`/components`) and serverless API routes (`app/api/.../route.ts`).
- `application/usecases/` — business-logic services (e.g., LoginUseCase, SearchMusicUseCase) and DTOs.
- `domain/` — core entities (Member, Music, Playlist, Video, etc.) and repository interfaces.
- `infra/repositories/` — concrete implementations connecting domain repositories to external systems: Supabase (Postgres), Spotify API, YouTube API.
- `hooks/`, `store/`, `utils/` — client-side utilities and state management (Zustand).
- Config files: `next.config.ts` (Next.js settings), `lib/supabase.ts` (Supabase client), `tsconfig.json`, etc.
- Public assets under `public/`.

##### README for additional insights
- Confirms Clean Architecture, tech stack (React, Next.js, TypeScript, Zustand, SASS, Supabase, Spotify API, YouTube API).
- Provides ERD showing Supabase tables for members, musics, playlists, playlist_videos, etc.
- Describes external API usage patterns (ISRC code from Spotify, OR‐based YouTube searches).

##### Main components and their relationships
a. Frontend (Next.js UI)
- Pages in `app/(anon)` for anonymous users and `app/(sign)` for auth flows
- Shared components in `app/components` + global utils/hooks
- Client-side state stores via Zustand (`store/`)
- Trigger API calls to `app/api/*` routes
b. API layer (Next.js Serverless Functions)
- Handlers under `app/api/*/route.ts` map HTTP requests to application use cases
- Perform input validation, authentication (cookies/JWT), then call use cases
c. Application Layer (Use Cases)
- Encapsulate application-specific business logic (e.g., CreatePlaylistUseCase)
- Receive DTOs from API, orchestrate domain operations, return DTOs
d. Domain Layer
- Entities model core concepts (Member, Music, Playlist, Video)
- Repository interfaces declare operations (IMemberRepository, MusicRepository, etc.)
e. Infra Layer
- Implements repository interfaces:
- SupabaseMemberRepository, SupabaseMusicRepository → Supabase (Postgres) via `lib/supabase.ts`
- SpotifyApiRepository → Spotify Web API (fetch ISRC and track data)
- YouTubeApiRepository / VideoRepository / VideoCommentRepository → YouTube Data API
f. Database (Supabase/Postgres)
- Tables: members, musics, playlists, playlist_videos, etc. as per ERD
g. External Services
- Spotify API (ISRC lookup, track info)
- YouTube Data API (search, comments, video info)

##### Architectural patterns and design principles
- Clean Architecture (four layers, Dependency Rule: outer layers depend on inner layers only via abstractions).
- Separation of concerns: UI vs. API routing vs. business logic vs. persistence.
- Dependency Injection: API handlers instantiate use cases with concrete infra repositories.
- Single-Responsibility: each module has one reason to change.
- Serverless functions (stateless handlers) for scalability and Vercel deployment.

##### Final advice
- Be exhaustive: include every major module (pages, API routes, use cases, repos).
- Don’t overcrowd: group modules logically and expose only public interfaces.
- Data flows for the critical user journeys:
- User logs in → LoginUseCase → MemberRepository (Supabase).
- User extracts tracks → GetVideoContentsUseCase → YouTubeRepo → Domain → UI.
- User searches → SearchMusicUseCase → SpotifyRepo → YouTubeRepo.
- User creates playlist → CreatePlaylistUseCase → PlaylistRepo + PlaylistMusicRepo.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Client Layer
    subgraph "Client (Browser)"
        direction TB
        anonPages["Anonymous Pages"]:::frontend
        signPages["Auth Pages"]:::frontend
        sharedComponents["Shared Components"]:::frontend
        subgraph "Global Layout & Styles"
            direction TB
            globalLayout["app/layout.tsx"]:::frontend
            globalStyles["app/global.scss"]:::frontend
            anonLayout["app/(anon)/layout.tsx"]:::frontend
            signLayout["app/(sign)/layout.tsx"]:::frontend
        end
        subgraph "State Stores (Zustand)"
            direction TB
            authStore["authStore.ts"]:::frontend
            playlistStore["usePlaylistStore.ts"]:::frontend
            toastStore["toast.ts"]:::frontend
        end
        subgraph "Hooks"
            direction TB
            useAuth["useAuth.ts"]:::frontend
            useModal["useModal.ts"]:::frontend
            useToast["useToast.ts"]:::frontend
            useVideoExtract["useVideoExtract.ts"]:::frontend
        end
    end

    %% CDN/Static Assets
    subgraph "CDN / Static Assets"
        publicAssets["public/"]:::frontend
    end

    %% Server Layer
    subgraph "Next.js Server (Serverless)"
        direction TB
        apiLayer["API Layer\n(app/api/*)"]:::api
        ssrFunctions["SSR/SSG Functions"]:::api
    end

    %% Application Layer
    subgraph "Application Layer"
        direction TB
        usecases["Use Cases\n(application/usecases)"]:::app
    end

    %% Domain Layer
    subgraph "Domain Layer"
        direction TB
        domainEntities["Entities\n(domain/entities)"]:::domain
        repoInterfaces["Repository Interfaces\n(domain/repositories)"]:::domain
    end

    %% Infra Layer
    subgraph "Infra Layer"
        direction TB
        supabaseRepos["Supabase Repositories\n(infra/repositories/supabase)"]:::infra
        spotifyRepo["Spotify API Repository\n(infra/repositories/spotify)"]:::infra
        youtubeRepo["YouTube API Repositories\n(infra/repositories/youtube)"]:::infra
        supabaseClient["Supabase Client\n(lib/supabase.ts)"]:::infra
    end

    %% Database
    db[(Supabase/Postgres)]:::db

    %% External Services
    cloudSpotify((Spotify API)):::external
    cloudYouTube((YouTube Data API)):::external

    %% Connections
    anonPages -->|HTTP| ssrFunctions
    signPages -->|HTTP| ssrFunctions
    anonPages -->|HTTP| apiLayer
    signPages -->|HTTP| apiLayer
    sharedComponents --> anonPages
    sharedComponents --> signPages
    authStore --> anonPages
    authStore --> signPages
    playlistStore --> anonPages
    playlistStore --> signPages
    toastStore --> anonPages
    toastStore --> signPages
    useAuth --> anonPages
    useAuth --> signPages
    useModal --> anonPages
    useToast --> anonPages
    useVideoExtract --> anonPages

    publicAssets --> anonPages
    publicAssets --> signPages

    apiLayer -->|calls| usecases
    ssrFunctions -->|calls| usecases

    usecases -->|uses| domainEntities
    usecases -->|depends on| repoInterfaces

    repoInterfaces -->|implemented by| supabaseRepos
    repoInterfaces -->|implemented by| spotifyRepo
    repoInterfaces -->|implemented by| youtubeRepo

    supabaseRepos -->|SQL/TLS| db
    supabaseClient -->|SQL/TLS| db

    spotifyRepo -->|HTTPS| cloudSpotify
    youtubeRepo -->|HTTPS| cloudYouTube

    %% Click Events
    click anonPages "https://github.com/front-end-bootcamp-plus-4/jackpot_plug/tree/dev/app/(anon)"
    click signPages "https://github.com/front-end-bootcamp-plus-4/jackpot_plug/tree/dev/app/(sign)"
    click sharedComponents "https://github.com/front-end-bootcamp-plus-4/jackpot_plug/tree/dev/app/components"
    click globalLayout "https://github.com/front-end-bootcamp-plus-4/jackpot_plug/blob/dev/app/layout.tsx"
    click globalStyles "https://github.com/front-end-bootcamp-plus-4/jackpot_plug/blob/dev/app/global.scss"
    click anonLayout "https://github.com/front-end-bootcamp-plus-4/jackpot_plug/blob/dev/app/(anon)/layout.tsx"
    click signLayout "https://github.com/front-end-bootcamp-plus-4/jackpot_plug/blob/dev/app/(sign)/layout.tsx"
    click authStore "https://github.com/front-end-bootcamp-plus-4/jackpot_plug/blob/dev/store/authStore.ts"
    click playlistStore "https://github.com/front-end-bootcamp-plus-4/jackpot_plug/blob/dev/store/usePlaylistStore.ts"
    click toastStore "https://github.com/front-end-bootcamp-plus-4/jackpot_plug/blob/dev/store/toast.ts"
    click useAuth "https://github.com/front-end-bootcamp-plus-4/jackpot_plug/blob/dev/hooks/useAuth.ts"
    click useModal "https://github.com/front-end-bootcamp-plus-4/jackpot_plug/blob/dev/hooks/useModal.ts"
    click useToast "https://github.com/front-end-bootcamp-plus-4/jackpot_plug/blob/dev/hooks/useToast.ts"
    click useVideoExtract "https://github.com/front-end-bootcamp-plus-4/jackpot_plug/blob/dev/hooks/useVideoExtract.ts"
    click apiLayer "https://github.com/front-end-bootcamp-plus-4/jackpot_plug/tree/dev/app/api"
    click usecases "https://github.com/front-end-bootcamp-plus-4/jackpot_plug/tree/dev/application/usecases"
    click domainEntities "https://github.com/front-end-bootcamp-plus-4/jackpot_plug/tree/dev/domain/entities"
    click repoInterfaces "https://github.com/front-end-bootcamp-plus-4/jackpot_plug/tree/dev/domain/repositories"
    click supabaseRepos "https://github.com/front-end-bootcamp-plus-4/jackpot_plug/tree/dev/infra/repositories/supabase"
    click spotifyRepo "https://github.com/front-end-bootcamp-plus-4/jackpot_plug/tree/dev/infra/repositories/spotify"
    click youtubeRepo "https://github.com/front-end-bootcamp-plus-4/jackpot_plug/tree/dev/infra/repositories/youtube"
    click supabaseClient "https://github.com/front-end-bootcamp-plus-4/jackpot_plug/blob/dev/lib/supabase.ts"

    %% Styles
    classDef frontend fill:#E0F7FA,stroke:#006064,color:#006064;
    classDef api fill:#E1F5FE,stroke:#0D47A1,color:#0D47A1;
    classDef app fill:#FFF3E0,stroke:#E65100,color:#E65100;
    classDef domain fill:#F3E5F5,stroke:#4A148C,color:#4A148C;
    classDef infra fill:#E8F5E9,stroke:#1B5E20,color:#1B5E20;
    classDef db fill:#C8E6C9,stroke:#2E7D32,color:#2E7D32;
    classDef external fill:#FFE0B2,stroke:#EF6C00,color:#EF6C00;
```
