Architecture

Sargam is an offline-capable, serverless Progressive Web Application (PWA) built for discovery and continuous playback of golden-era Indian music. It separates runtime application delivery from the offline data pipeline, hosting zero copyrighted audio while enabling instant, sub-millisecond search across thousands of songs.

System Topology

Listener / Device (PWA Standalone Shell)

↓

Next.js 16 Client Shell (Static Prerendered + TanStack Query)

↓

Discovery Layer (Aajcha Sargam, Eras, Marathi Spotlight, Facets)

↓

Sargam Versioned Catalog (Indexed Compact JSON, Append-Only Ledger)

↓

Unified PlayerProvider (Root Layout Sibling + Media Session API)

↓

Authorized Playback Stream (Official YouTube Iframe API)

Runtime Specifications

Catalog Size: 3,916 songs in an indexed 632 KB JSON payload
Languages: Multi-language architecture (Hindi Foundation & Marathi Spotlight)
Stations & Facets: 66 stations, 415 artists, 1,379 films, 23 composers, 12 lyricists
Web Stack: Next.js 16 (App Router), React 19, Tailwind CSS v4, Base UI
Audio Engine: YouTube IFrame Player API with persistent root layout host
Client Storage: Four privacy-focused localStorage keys (sargam namespace with legacy migration)

The catalog is downloaded once and cached by TanStack React Query and the Service Worker. Because track lists are virtualized via react-virtuoso, rendering thousands of songs consumes minimal DOM memory, delivering 60 FPS scrolling on mobile hardware.

The Player Lives Above the Pages

Playback runs inside an official YouTube embedded iframe. Because an iframe cannot survive being unmounted, the player lives in the root layout (web/app/layout.tsx) as a sibling to the application frame rather than a child of any individual route. Navigating between Discover, Stations, Languages, or Search never re-mounts the player or interrupts audio.

<Providers>            // TanStack Query + Service Worker lifecycle
  <PlayerProvider>      // Manages iframe instance, queue, shuffle, & media session
    <AppFrame>
      {children}        // ← Navigation remounts this container only
    </AppFrame>
    <OfflineNotice />
  </PlayerProvider>
</Providers>

web/app/layout.tsx — Persistent player layout architecture

Sargam Catalog Engine (Python Pipeline)

A dedicated Python data pipeline in catalog/ handles discography ingestion, normalization, entity resolution, and verification before data reaches users.

1IngestionNormalizes discographies, trims audio rip artifacts, and canonicalizes metadata.
2Append-Only LedgerGuarantees permanent song IDs in data/song_ids.json so updates never break saved playlists.
3Entity EnrichmentResolves artists, eras (1950s–1980s), and regional taxonomies (Bhavgeet, Natya Sangeet).
4Embed VerificationEvery YouTube link is verified against YouTube's oEmbed endpoint to guarantee playback.
5PublishingEmits indexed, versioned JSON (v1.0.0 Hindi, v1.1.0 Marathi) for production web delivery.

Storage & Transparent Migration

Sargam operates with zero server-side authentication. User state is stored locally under the sargam: namespace:

• sargam:favorites — Saved song IDs
• sargam:history — Recently played track IDs
• sargam:backdrop — Selected ambient backdrop theme
• sargam.installDismissed — PWA install banner preference

Transparent migration automatically detects and converts legacy keys upon application boot, ensuring listeners never lose their liked songs or custom backdrops.

Open Source & Attribution

Sargam was inspired by the open-source architecture of Mehfil by Shashwat Tripathi. Complete upstream attribution, artist photograph provenance from Wikimedia Commons, and station artwork credits are documented in our About page and repository documentation.

Sargam on GitHub