# cgzirim/seek-tune architecture

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

- Interactive diagram: https://gitdiagram.com/cgzirim/seek-tune
- Repository: https://github.com/cgzirim/seek-tune

## Overview

##### Project type and purpose
- SeekTune is a full‑stack song‑recognition web application implementing Shazam’s audio‑fingerprinting algorithm.
- It exposes a React frontend (in “client/”) served by a Go backend API (in “server/”).
- The backend handles audio processing, fingerprint generation, database storage (SQLite or MongoDB), and external API integrations (Spotify & YouTube).

##### File structure
- Top‑level: Docker (Dockerfile, docker‑compose.yml, .env.example), orchestration scripts (scripts/), README, LICENSE.
- “client/”: React app with public assets (including WebAssembly runtime, compiled .wasm), source components, CSS modules.
- “server/”: Go modules for:
– HTTP entrypoint (main.go, socketHandlers.go, cmdHandlers.go)
– Audio I/O and conversion (wav/)
– Fingerprinting algorithm (shazam/)
– Database adapters (db/client.go, mongo.go, sqlite.go)
– External APIs (spotify/, including download and YouTube fallback)
– Utility packages (utils/logger, helpers).
- There’s also a “server/wasm/” directory—Go code compiled to WASM for client‑side fingerprinting.

##### README for technical stack and flow
- Frontend: React, WebAssembly (WASM), communicates via HTTP/S or WebSocket to the Go server.
- Backend: Golang HTTP server, uses ffmpeg for conversions, persists fingerprints and track metadata to SQLite or MongoDB.
- External services: Spotify API (to fetch metadata and track audio), YouTube (to download tracks).

##### Main components & their interactions
a. Frontend (React + WASM)
– Hosts UI (App.js, components/)
– Loads WebAssembly fingerprinting engine (main.wasm + wasm_exec.js)
– Captures audio input or references local files, generates fingerprint locally or sends to server for processing
– Sends REST / WebSocket requests to backend endpoints.
b. Backend API (Go server)
– HTTP Server (main.go) routes requests (download, save, find, erase) to command handlers.
– Audio conversion pipeline (wav/convert.go + ffmpeg)
– Fingerprinting engine (shazam/) used for matching.
– Database layer (db/) abstracts SQLite or Mongo connections.
– External integration (spotify/ & youtube fallback) for fetching audio and metadata.
c. Database
– SQLite (default) or MongoDB (via env vars).
– Stores song metadata, fingerprints, match results.
d. External Services
– Spotify Web API
– YouTube (for audio download)
– FFmpeg (local binary invoked by backend).

##### Architectural patterns & principles
- Layered architecture: Presentation (frontend), Application/API, Domain (fingerprinting logic), Infrastructure (DB + external APIs).
- Modular design: Each concern in its own package (shazam, wav, spotify, db).
- Use of WebAssembly to offload fingerprint generation to client (optional path).
- Configuration via environment variables, containerized deployment with Docker Compose.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User/Browser Tier
    subgraph "User/Browser Tier"
        Browser["Browser / UI"]:::frontend
    end

    %% Frontend Tier
    subgraph "Frontend Layer"
        AppJS["App.js"]:::frontend
        Components["components/"]:::frontend
        Index["index.js"]:::frontend
        WasmBinary["main.wasm"]:::frontend
        WasmExec["wasm_exec.js"]:::frontend
    end

    %% Backend Tier
    subgraph "Backend Layer"
        subgraph "Go HTTP Server"
            HTTPMain["main.go"]:::backend
            Socket["socketHandlers.go"]:::backend
            Cmd["cmdHandlers.go"]:::backend
        end
        subgraph "Audio Conversion Service"
            Conv1["convert.go"]:::backend
            Conv2["wav.go"]:::backend
        end
        subgraph "Fingerprinting Service"
            FFT["fft.go"]:::backend
            FP["fingerprint.go"]:::backend
            Image["image.go"]:::backend
            ShazamMain["shazam.go"]:::backend
            Spectrogram["spectrogram.go"]:::backend
        end
        subgraph "Database Adapter"
            DBClient["client.go"]:::backend
            SQLiteAdapter["sqlite.go"]:::backend
            MongoAdapter["mongo.go"]:::backend
        end
        subgraph "Spotify Integration"
            SpotifyMain["spotify.go"]:::backend
            Downloader["downloader.go"]:::backend
            SpotifyUtils["utils.go"]:::backend
        end
        YTdl["youtube.go"]:::backend
        subgraph "Utils"
            Logger["logger.go"]:::backend
            Helpers["helpers.go"]:::backend
            UtilsCore["utils.go"]:::backend
        end
    end

    %% Infrastructure Layer
    subgraph "Infrastructure & External Services"
        SQLiteDB["SQLite DB"]:::infra
        MongoDB["MongoDB"]:::infra
        SpotifyAPI["Spotify Web API"]:::infra
        YTService["YouTube Service"]:::infra
        FFmpeg["FFmpeg CLI"]:::infra
    end

    %% Relationships
    Browser -->|HTTP/WebSocket| HTTPMain
    AppJS -->|"loads"| WasmBinary
    AppJS -->|"loads"| WasmExec
    Browser -->|UI Render| AppJS
    HTTPMain -->|"convert request"| Conv1
    Conv1 -->|"calls"| Conv2
    Conv2 -->|"uses"| FFmpeg
    Conv2 -->|"passes WAV"| ShazamMain
    ShazamMain -->|"generates fingerprint"| DBClient
    HTTPMain -->|"download metadata"| SpotifyMain
    SpotifyMain -->|"fetch audio"| SpotifyAPI
    HTTPMain -->|"fallback download"| YTdl
    YTdl -->|"download audio"| YTService
    HTTPMain -->|"invoke fingerprint on server"| ShazamMain
    WasmBinary -.->|"optional client-side fingerprint"| ShazamMain
    DBClient -->|"stores/query"| SQLiteDB
    DBClient -->|"stores/query"| MongoDB

    %% Click Events
    click AppJS "https://github.com/cgzirim/seek-tune/blob/main/client/src/App.js"
    click Components "https://github.com/cgzirim/seek-tune/tree/main/client/src/components/"
    click Index "https://github.com/cgzirim/seek-tune/blob/main/client/src/index.js"
    click WasmBinary "https://github.com/cgzirim/seek-tune/blob/main/client/public/main.wasm"
    click WasmExec "https://github.com/cgzirim/seek-tune/blob/main/client/public/wasm_exec.js"
    click HTTPMain "https://github.com/cgzirim/seek-tune/blob/main/server/main.go"
    click Socket "https://github.com/cgzirim/seek-tune/blob/main/server/socketHandlers.go"
    click Cmd "https://github.com/cgzirim/seek-tune/blob/main/server/cmdHandlers.go"
    click Conv1 "https://github.com/cgzirim/seek-tune/blob/main/server/wav/convert.go"
    click Conv2 "https://github.com/cgzirim/seek-tune/blob/main/server/wav/wav.go"
    click FFT "https://github.com/cgzirim/seek-tune/blob/main/server/shazam/fft.go"
    click FP "https://github.com/cgzirim/seek-tune/blob/main/server/shazam/fingerprint.go"
    click Image "https://github.com/cgzirim/seek-tune/blob/main/server/shazam/image.go"
    click ShazamMain "https://github.com/cgzirim/seek-tune/blob/main/server/shazam/shazam.go"
    click Spectrogram "https://github.com/cgzirim/seek-tune/blob/main/server/shazam/spectrogram.go"
    click DBClient "https://github.com/cgzirim/seek-tune/blob/main/server/db/client.go"
    click SQLiteAdapter "https://github.com/cgzirim/seek-tune/blob/main/server/db/sqlite.go"
    click MongoAdapter "https://github.com/cgzirim/seek-tune/blob/main/server/db/mongo.go"
    click SpotifyMain "https://github.com/cgzirim/seek-tune/blob/main/server/spotify/spotify.go"
    click Downloader "https://github.com/cgzirim/seek-tune/blob/main/server/spotify/downloader.go"
    click SpotifyUtils "https://github.com/cgzirim/seek-tune/blob/main/server/spotify/utils.go"
    click YTdl "https://github.com/cgzirim/seek-tune/blob/main/server/spotify/youtube.go"
    click Logger "https://github.com/cgzirim/seek-tune/blob/main/server/utils/logger.go"
    click Helpers "https://github.com/cgzirim/seek-tune/blob/main/server/utils/helpers.go"
    click UtilsCore "https://github.com/cgzirim/seek-tune/blob/main/server/utils/utils.go"

    %% Styles
    classDef frontend fill:#e0f7e9,stroke:#27a745,stroke-width:1px
    classDef backend fill:#e8f0fe,stroke:#4285f4,stroke-width:1px
    classDef infra fill:#fff3e0,stroke:#fb8c00,stroke-width:1px
    classDef optional stroke-dasharray: 5 5,fill:#f5f5f5,stroke:#9e9e9e,stroke-width:1px
```
