# kudesn1k1/go-shazam architecture

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

- Interactive diagram: https://gitdiagram.com/kudesn1k1/go-shazam
- Repository: https://github.com/kudesn1k1/go-shazam

## Overview

##### Project Type and Purpose
- This is a self-hosted, full-stack music-recognition platform (“go-shazam”) with a Vue.js SPA frontend, a Go/Gin HTTP API, and a background worker service. It uses audio-fingerprinting to match samples against a song library, integrates with Spotify (and optionally YouTube), and persists data in PostgreSQL while using Redis as a job queue.

##### High-Level Architecture
The system can be divided into five main tiers:
a. Client Layer
- Vue.js Single-Page Application served by Nginx (Docker container).
b. API Layer
- Go + Gin HTTP server, handles authentication (JWT), REST endpoints for recognition, song management, user management.
c. Background Processing Layer
- A Worker service (separate Go binary) that pulls tasks from Redis, processes audio (fragmentation, peak detection, hashing), interacts with Spotify/YouTube, and writes results to PostgreSQL.
d. Data Layer
- PostgreSQL database for users, songs, fingerprints, recognition results.
e. Infrastructure and External Integrations
- Redis queue for async jobs
- External APIs: Spotify (metadata), YouTube (download)

##### Essential Details to Capture
- Separation of concerns: don’t lump everything into “backend”—show distinct HTTP and Worker processes.
- Async flow: Redis queue sits between API and Worker.
- Database interactions: show transaction manager, repositories, schema migrations (optional detail).
- Authentication flow: client obtains JWT, API middleware verifies tokens before hitting handlers.

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph "Frontend Layer"
        direction TB
        NGINX["Nginx (Docker)"]:::frontend
        SPA["Vue.js SPA"]:::frontend
    end

    subgraph "Backend Layer"
        direction TB
        subgraph "API Server (Go + Gin)"
            direction TB
            Main["main.go"]:::backend
            HTTP["HTTP Setup & Routes"]:::backend
            Auth["Auth Module (JWT)"]:::backend
            User["User Module"]:::backend
            Song["Song Module"]:::backend
            Recognition["Recognition Module"]:::backend
            FingerprintAPI["Fingerprint Module"]:::backend
            SpotifyAPI["Spotify Integration"]:::backend
            YouTubeAPI["YouTube Integration"]:::backend
            DBAPI["PostgreSQL Client"]:::backend
            QueueAPI["Redis Queue Client"]:::backend
        end

        subgraph "Worker Service (Go CLI)"
            direction TB
            WorkerMain["worker/main.go"]:::backend
            QueueWorker["Queue Module"]:::backend
            AudioProc["Audio Processor"]:::backend
            FingerprintW["Fingerprint Module"]:::backend
            SpotifyW["Spotify Integration"]:::backend
            YouTubeW["YouTube Integration"]:::backend
            DBWorker["PostgreSQL Client"]:::backend
        end
    end

    subgraph "Data Stores"
        direction TB
        Redis["Redis (Queue)"]:::data
        Postgres["PostgreSQL"]:::data
    end

    subgraph "External Services"
        direction TB
        SpotifyExt["Spotify API"]:::external
        YouTubeExt["YouTube"]:::external
    end

    %% Connections
    SPA -->|"serves static over HTTP"| NGINX
    NGINX -->|"HTTP requests"| HTTP
    HTTP -->|"SQL queries"| DBAPI
    HTTP -->|"enqueue jobs (PUSH)"| QueueAPI
    QueueAPI -->|"PUBLISH"| Redis
    Redis -->|"POP jobs"| QueueWorker
    QueueWorker -->|"process loop"| AudioProc
    AudioProc -->|"extract peaks & hash"| FingerprintW
    FingerprintW -->|"persist results"| DBWorker
    QueueWorker -->|"fetch metadata"| SpotifyW
    QueueWorker -->|"download audio"| YouTubeW
    DBAPI -->|"reads/writes"| Postgres
    DBWorker -->|"writes"| Postgres
    HTTP -->|"fetch metadata"| SpotifyAPI
    HTTP -->|"download audio (optional)"| YouTubeAPI
    HTTP -->|"JSON responses"| SPA
    SpotifyW -->|"API calls"| SpotifyExt
    YouTubeW -->|"download requests"| YouTubeExt
    SpotifyAPI -->|"API calls"| SpotifyExt
    YouTubeAPI -->|"download requests"| YouTubeExt

    %% Click Events - Frontend
    click SPA "https://github.com/kudesn1k1/go-shazam/tree/main/client/src"
    click NGINX "https://github.com/kudesn1k1/go-shazam/blob/main/client/nginx.conf"
    click NGINX "https://github.com/kudesn1k1/go-shazam/tree/main/client/Dockerfile"
    click SPA "https://github.com/kudesn1k1/go-shazam/blob/main/client/index.html"

    %% Click Events - API Server
    click Main "https://github.com/kudesn1k1/go-shazam/blob/main/server/cmd/server/main.go"
    click HTTP "https://github.com/kudesn1k1/go-shazam/blob/main/server/internal/http/http.go"
    click HTTP "https://github.com/kudesn1k1/go-shazam/blob/main/server/internal/http/config.go"
    click HTTP "https://github.com/kudesn1k1/go-shazam/blob/main/server/internal/http/cors.go"
    click Auth "https://github.com/kudesn1k1/go-shazam/tree/main/server/internal/auth"
    click User "https://github.com/kudesn1k1/go-shazam/tree/main/server/internal/user"
    click Song "https://github.com/kudesn1k1/go-shazam/tree/main/server/internal/song"
    click Recognition "https://github.com/kudesn1k1/go-shazam/tree/main/server/internal/recognition"
    click FingerprintAPI "https://github.com/kudesn1k1/go-shazam/tree/main/server/internal/fingerprint"
    click SpotifyAPI "https://github.com/kudesn1k1/go-shazam/tree/main/server/internal/spotify"
    click YouTubeAPI "https://github.com/kudesn1k1/go-shazam/tree/main/server/internal/youtube"
    click DBAPI "https://github.com/kudesn1k1/go-shazam/tree/main/server/internal/core/db"
    click QueueAPI "https://github.com/kudesn1k1/go-shazam/tree/main/server/internal/queue"

    %% Click Events - Worker Service
    click WorkerMain "https://github.com/kudesn1k1/go-shazam/blob/main/server/cmd/worker/main.go"
    click QueueWorker "https://github.com/kudesn1k1/go-shazam/tree/main/server/internal/queue"
    click AudioProc "https://github.com/kudesn1k1/go-shazam/blob/main/server/internal/audio/processor.go"
    click FingerprintW "https://github.com/kudesn1k1/go-shazam/tree/main/server/internal/fingerprint"
    click SpotifyW "https://github.com/kudesn1k1/go-shazam/tree/main/server/internal/spotify"
    click YouTubeW "https://github.com/kudesn1k1/go-shazam/tree/main/server/internal/youtube"
    click DBWorker "https://github.com/kudesn1k1/go-shazam/tree/main/server/internal/core/db"

    %% Click Events - Data Layer & Infra
    click Redis "https://github.com/kudesn1k1/go-shazam/blob/main/server/internal/queue/config.go"
    click Redis "https://github.com/kudesn1k1/go-shazam/blob/main/server/internal/queue/service.go"
    click Redis "https://github.com/kudesn1k1/go-shazam/blob/main/server/internal/queue/worker.go"
    click Postgres "https://github.com/kudesn1k1/go-shazam/blob/main/server/migrations/20241121000000_init.sql"
    click Postgres "https://github.com/kudesn1k1/go-shazam/blob/main/server/migrations/20241125000000_users.sql"
    click Postgres "https://github.com/kudesn1k1/go-shazam/blob/main/docker-compose.yml"

    %% Styles
    classDef frontend fill:#D0E8FF,stroke:#0366d6,color:#024b91;
    classDef backend fill:#DFFFE0,stroke:#2c662d,color:#1a3d12;
    classDef data fill:#FFE5B4,stroke:#d97706,color:#8c4a03,stroke-dasharray: 5 5;
    classDef external fill:#F0F0F0,stroke:#6a737d,color:#24292e,stroke-dasharray: 5 5;
```
