# nikh7l/shazam architecture

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

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

## Overview

##### Main Components
- Frontend (React + Vite SPA)
- Backend (Flask REST API + WebSockets)
- Core Fingerprinting Engine (Python library: `shazam_core`)
- Database (SQLite via `db_handler`)
- Background Task Runner (Python `concurrent.futures`)
- External Services (Spotify API, YouTube API/DL)

##### Relationships & Data Flows
a. User Interaction
- Browser captures audio (MediaRecorder API) → React UI “Listen” component
- React sends audio blob via HTTP POST or WebSocket → Backend `/match` endpoint or WS route
b. Matching Flow
- Flask routes (`backend/routes/songs.py`, `websockets.py`) receive audio →
- Pass audio to Fingerprinting Service (`services/song_ingester.py` for ingestion, or match service) →
- Fingerprinting Engine (`shazam_core` modules: `spectrogram.py` → `peak_finding.py` → `fingerprinting.py` → combinatorial hashes) →
- Query SQLite via `db_handler` to find best match →
- Return match data (song metadata + YouTube link) → React displays results
c. Ingestion Flow (Admin Panel → Background Task)
- React Admin form hits `/ingest` endpoint →
- Backend `song_ingester.py` enqueues job into `concurrent.futures` thread pool →
- Worker downloads track(s) (Spotipy, yt-dlp) →
- Processes through Fingerprinting Engine →
- Stores fingerprint hashes and metadata into SQLite via `db_handler` →
- Reports ingestion status via WS or REST status endpoint

##### Architectural Patterns & Principles
- Layered Responsibility:
- Presentation Layer (React)
- API Layer (Flask routes + WS)
- Service Layer (`services/` orchestrates flows)
- Core Library Layer (`shazam_core` for pure audio logic)
- Persistence Layer (`database/db_handler`, migrations)
- Separation of Concerns: audio I/O, business logic, data access, external API interactions are all modular.
- Asynchronous Background Processing: use of thread pool for nonblocking ingestion tasks.
- External Integration Adapters: `api_clients/spotify_client.py`, `youtube_client.py`.

##### Call Out Key Technologies
- Frontend: React, Vite, Fetch API, WebSocket, react-youtube
- Backend: Python 3, Flask, Waitress (prod WSGI), `pydub`, `numpy`, `scipy`
- DB: SQLite, raw SQL + migrations
- Audio Fingerprinting: custom spectrogram/peak hash algorithm
- External APIs: Spotipy, yt-dlp

- Use arrowheads to denote request/response directions.

##### Detail Without Clutter

- Clearly identifies every major piece of the system
- Shows how data flows end‐to‐end (from mic to match result)
- Highlights both real‐time matching and background ingestion processes
- Distinguishes between internal modules, infrastructure, and third‐party services

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Browser & Frontend
    Browser["User Browser"]:::external
    subgraph "Frontend (React + Vite SPA)"
        classDef frontend fill:#cce5ff,stroke:#337ab7;
        HomePage["HomePage.jsx"]:::frontend
        AdminPage["AdminPage.jsx"]:::frontend
        ListenButton["ListenButton.jsx"]:::frontend
        ResultsDisplay["ResultsDisplay.jsx"]:::frontend
        AddSongForm["AddSongForm.jsx"]:::frontend
        SpotifyIngestForm["SpotifyIngestForm.jsx"]:::frontend
        APIService["apiService.js"]:::frontend
        WSService["websocketService.js"]:::frontend
    end

    Browser -->|"click Listen"| ListenButton
    Browser -->|"navigate"| HomePage
    Browser -->|"navigate"| AdminPage
    ListenButton -->|"records audio"| APIService
    APIService -->|"POST /match"| BackendAPI
    APIService -->|"POST /ingest"| BackendAPI
    WSService -->|"WS connect"| BackendWS

    click HomePage "https://github.com/nikh7l/shazam/blob/main/frontend/src/pages/HomePage.jsx"
    click AdminPage "https://github.com/nikh7l/shazam/blob/main/frontend/src/pages/AdminPage.jsx"
    click ListenButton "https://github.com/nikh7l/shazam/blob/main/frontend/src/components/ListenButton.jsx"
    click ResultsDisplay "https://github.com/nikh7l/shazam/blob/main/frontend/src/components/ResultsDisplay.jsx"
    click AddSongForm "https://github.com/nikh7l/shazam/blob/main/frontend/src/components/AddSongForm.jsx"
    click SpotifyIngestForm "https://github.com/nikh7l/shazam/blob/main/frontend/src/components/SpotifyIngestForm.jsx"
    click APIService "https://github.com/nikh7l/shazam/blob/main/frontend/src/services/apiService.js"
    click WSService "https://github.com/nikh7l/shazam/blob/main/frontend/src/services/websocketService.js"

    %% Backend
    subgraph "Backend (Flask API + WS)" 
        classDef backend fill:#dff0d8,stroke:#3c763d;
        BackendAPI["REST API Router"]:::backend
        BackendWS["WebSocket Handler"]:::backend
        subgraph "Service Layer"
            SongIngester["song_ingester.py"]:::backend
        end
        subgraph "API Clients"
            SpotifyClient["spotify_client.py"]:::backend
            YouTubeClient["youtube_client.py"]:::backend
        end
        subgraph "Background Worker Pool"
            WorkerPool["ThreadPool Executor"]:::backend
        end
        AppEntry["app.py"]:::backend
    end

    APIService --> BackendAPI
    BackendAPI -->|"calls ingest"| SongIngester
    BackendAPI -->|"calls match"| SongIngester
    BackendWS -->|"stream audio"| SongIngester
    SongIngester --> WorkerPool
    WorkerPool --> SongIngester
    SongIngester --> SpotifyClient
    SongIngester --> YouTubeClient

    AppEntry --> BackendAPI
    AppEntry --> BackendWS

    click AppEntry "https://github.com/nikh7l/shazam/blob/main/backend/app.py"
    click BackendAPI "https://github.com/nikh7l/shazam/blob/main/backend/routes/songs.py"
    click BackendAPI "https://github.com/nikh7l/shazam/blob/main/backend/routes/stats.py"
    click BackendWS "https://github.com/nikh7l/shazam/blob/main/backend/routes/websockets.py"
    click SongIngester "https://github.com/nikh7l/shazam/blob/main/backend/services/song_ingester.py"
    click SpotifyClient "https://github.com/nikh7l/shazam/blob/main/backend/api_clients/spotify_client.py"
    click YouTubeClient "https://github.com/nikh7l/shazam/blob/main/backend/api_clients/youtube_client.py"

    %% Core Fingerprinting Engine
    subgraph "Fingerprinting Engine (shazam_core)" 
        classDef core fill:#fcf8e3,stroke:#8a6d3b;
        AudioUtils["audio_utils.py"]:::core
        Spectrogram["spectrogram.py"]:::core
        PeakFinding["peak_finding.py"]:::core
        Fingerprinting["fingerprinting.py"]:::core
    end

    SongIngester --> AudioUtils
    AudioUtils --> Spectrogram
    Spectrogram --> PeakFinding
    PeakFinding --> Fingerprinting

    click AudioUtils "https://github.com/nikh7l/shazam/blob/main/backend/shazam_core/audio_utils.py"
    click Spectrogram "https://github.com/nikh7l/shazam/blob/main/backend/shazam_core/spectrogram.py"
    click PeakFinding "https://github.com/nikh7l/shazam/blob/main/backend/shazam_core/peak_finding.py"
    click Fingerprinting "https://github.com/nikh7l/shazam/blob/main/backend/shazam_core/fingerprinting.py"

    %% Database
    Database["SQLite Database"]:::db
    SongIngester -->|"read/write"| Database
    Fingerprinting -->|"query hashes"| Database

    click Database "https://github.com/nikh7l/shazam/blob/main/backend/database/db_handler.py"

    %% Migrations/Schemas
    Schema["schema.sql"]:::db
    Migrations["v2_add_task_tracking.py"]:::db
    Database --> Schema
    Database --> Migrations

    click Schema "https://github.com/nikh7l/shazam/blob/main/backend/database/schema.sql"
    click Migrations "https://github.com/nikh7l/shazam/blob/main/backend/database/migrations/v2_add_task_tracking.py"

    %% External Services
    subgraph "External APIs"
        classDef externalAPI fill:#fcf8ff,stroke:#5b5ea6;
        SpotifyAPI["Spotify API"]:::externalAPI
        YouTubeAPI["YouTube API/DL"]:::externalAPI
    end

    SpotifyClient -->|"fetch track"| SpotifyAPI
    YouTubeClient -->|"download video"| YouTubeAPI

    %% Styles
    class Browser external;
    classDef external fill:#f2f2f2,stroke:#999999;
    classDef externalAPI fill:#fff2cc,stroke:#9a7d0a;
    classDef db fill:#eeeeee,stroke:#666666;
    classDef core fill:#fcf8e3,stroke:#8a6d3b;
    classDef backend fill:#dff0d8,stroke:#3c763d;
    classDef frontend fill:#cce5ff,stroke:#337ab7;
```
