How kudesn1k1/go-shazam works
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.