Lens / Rishit Music — Private Audio Streaming Platform

Architecture

Rishit Music high-level designLogicalConceptual diagram
Rishit Music high-level design: see the component list below
Components and connections (13 / 22)
  • Listener Browser (Client): Next.js UI + persistent player + hls.js/native HLS.
  • Admin Browser (Client): Catalog CRUD, direct WAV upload, media state, retry and integrations management.
  • External App Browser (Client): Consumes a short-lived browser playback capability issued through its own trusted backend.
  • External App Backend (Service): Stores permanent MUSIC_SERVICE_KEY server-side and requests scoped sessions.
  • Tailwind + shadcn UI System (Component): Shared presentation primitives for listener and administration surfaces; keeps the product shell consistent without coupling media logic to view code.
  • Turborepo + Yarn 4 (Process): Workspace orchestration for the Next.js web application, NestJS API/worker source and shared packages.
  • Next.js Web (Service): Listener/admin shell deployed on Vercel.
  • Persistent Media Worker (Process): Atomically claims queued tracks, downloads WAV, probes/transcodes, uploads HLS, persists READY/FAILED.
  • NestJS API / Control Plane (Service): Auth, catalog, playlists, upload authorization, integration auth, playback session creation and HLS manifest authorization.
  • MongoDB (Database): Users, catalog, playlists, track processing state, playback events, integration credentials and usage buckets.
  • CloudFront + OAC (Network): Protected delivery for signed HLS init/segment URLs from private S3.
  • AWS STS AssumeRole (External): Turns restricted source credentials into temporary role credentials with S3 permissions.
  • Private S3 (Storage): uploads/source/* WAV masters and streams/* HLS derivatives.
  • Listener Browser to Next.js Web: loads UI
  • Admin Browser to Next.js Web: loads admin UI
  • Next.js Web to NestJS API / Control Plane: auth/catalog/playlists/playback APIs
  • Admin Browser to NestJS API / Control Plane: request presigned upload + complete/retry
  • Admin Browser to Private S3: direct presigned WAV PUT
  • NestJS API / Control Plane to MongoDB: catalog + state + events
  • Persistent Media Worker to MongoDB: claim/update processing state
  • Persistent Media Worker to Private S3: download WAV / upload HLS
  • NestJS API / Control Plane to Private S3: HEAD/read manifests/presign fallback
  • NestJS API / Control Plane to CloudFront + OAC: issues signed media URLs
  • Listener Browser to NestJS API / Control Plane: authorized HLS master/rendition manifests
  • Listener Browser to CloudFront + OAC: signed init.mp4 + .m4s
  • External App Backend to NestJS API / Control Plane: service key: catalog/session APIs
  • External App Browser to NestJS API / Control Plane: short-lived track capability
  • External App Browser to CloudFront + OAC: signed media URLs
  • NestJS API / Control Plane to AWS STS AssumeRole: assume role
  • Persistent Media Worker to AWS STS AssumeRole: assume role
  • AWS STS AssumeRole to Private S3: temporary role credentials
  • Tailwind + shadcn UI System to Next.js Web: styles / primitives
  • Turborepo + Yarn 4 to Next.js Web: builds
  • Turborepo + Yarn 4 to NestJS API / Control Plane: builds
  • Turborepo + Yarn 4 to Persistent Media Worker: builds worker source

Control plane / media byte plane split.

Rishit Music deploymentLogicalConceptual diagram
Rishit Music deployment: see the component list below
Components and connections (10 / 14)
  • GitHub Repository (External): Private monorepo source for web, API, media worker, Dockerfile and deployment/bootstrap scripts.
  • rishit.co.in / External Consumer (External): Example external application whose backend holds a service key and whose browser receives only short-lived playback capabilities.
  • Yarn 4.18 (Component): Immutable workspace install and script entrypoint for local, CI and deployment tooling.
  • Turborepo (Process): Build, lint, typecheck and application task orchestration across apps/* and packages/*.
  • music.rishit.co.in (Service): Next.js listener/admin application.
  • Persistent Node 22 + FFmpeg Worker (Process): Dockerfile.worker runtime on persistent compute; continuously polls MongoDB and performs FFprobe/FFmpeg media jobs.
  • api.music.rishit.co.in (Service): NestJS HTTP control plane: auth, catalog, media authorization, integrations and playback manifests.
  • MongoDB (Database): Catalog, auth, media state, playlists, integration keys, usage and playback events.
  • media.music.rishit.co.in / CloudFront (Network): Private-origin delivery of signed HLS init and media segments.
  • Private Amazon S3 (Storage): uploads/source/* WAV masters and streams/* HLS derivatives. Not public.
  • GitHub Repository to Yarn 4.18: source checkout
  • Yarn 4.18 to Turborepo: workspace scripts
  • Turborepo to music.rishit.co.in: build/deploy apps/web
  • Turborepo to api.music.rishit.co.in: build/deploy API
  • Turborepo to Persistent Node 22 + FFmpeg Worker: build worker image
  • music.rishit.co.in to api.music.rishit.co.in: HTTPS API
  • api.music.rishit.co.in to MongoDB: metadata / auth / state
  • Persistent Node 22 + FFmpeg Worker to MongoDB: atomic claim + result state
  • Persistent Node 22 + FFmpeg Worker to Private Amazon S3: download source / upload HLS
  • api.music.rishit.co.in to Private Amazon S3: HEAD / manifests / presign fallback
  • media.music.rishit.co.in / CloudFront to Private Amazon S3: private OAC origin
  • api.music.rishit.co.in to media.music.rishit.co.in / CloudFront: signs segment URLs
  • rishit.co.in / External Consumer to api.music.rishit.co.in: service integration + browser session
  • rishit.co.in / External Consumer to media.music.rishit.co.in / CloudFront: signed media bytes

Vercel web+API, persistent FFmpeg worker container, private S3, CloudFront OAC.

Auth and playback capability flowsLogicalConceptual diagram
Auth and playback capability flows: see the component list below
Components and connections (30 / 24)
  • User (Client)
  • NestJS Auth API (Service)
  • Auth API (Service)
  • Browser (Client)
  • JwtStrategy (Service)
  • Request context (Service)
  • Admin role guard (Client)
  • Admin controllers (Client)
  • Authenticated listener (Client)
  • PlaybackService (Service)
  • MongoDB Track (Service)
  • Browser / hls.js (Client)
  • Music API (Service)
  • Private media plane (Service)
  • External application backend (Service)
  • Integration API (Service)
  • IntegrationService (Service)
  • MongoDB (Service)
  • Integration request context (Service)
  • Scope guard (Service)
  • Integration endpoint (Service)
  • Integration policy (Service)
  • External backend/browser (Client)
  • External browser (Client)
  • Music API + CloudFront (Service)
  • Integration credential state (Service)
  • Admin (Client)
  • MongoDB IntegrationApp (Service)
  • Operator (Service)
  • External application (Service)
  • User to NestJS Auth API: 1. [User authentication] Submit credentials
  • Auth API to Browser: 2. Validate active user/password and issue general application JWT
  • Browser to JwtStrategy: 3. Send Authorization: Bearer <JWT> for protected application APIs
  • JwtStrategy to Request context: 4. Verify signature and expiration; attach user identity/roles
  • Admin role guard to Admin controllers: 5. Require ADMIN role before /api/admin/* operations
  • Authenticated listener to PlaybackService: 6. [First-party playback] Request a session for one track
  • PlaybackService to MongoDB Track: 7. Require status=READY, published=true and masterPlaylistKey
  • PlaybackService to Browser: 8. Mint audience=music-hls JWT containing type=playback-hls and trackId with bounded TTL
  • Browser / hls.js to Music API: 9. Request authorized master.m3u8 with the short-lived playback token
  • Music API to Browser: 10. Verify token audience/type/expiry and exact track binding; rewrite rendition URIs back through authorized API routes
  • Browser / hls.js to Music API: 11. Request one rendition playlist with the same playback capability
  • Music API to Browser: 12. Normalize relative media paths, reject directory escape, and replace init/segment URIs with short-lived signed media URLs
  • Browser to Private media plane: 13. Fetch init.mp4 and .m4s directly using signed CloudFront URLs; use S3 presigned GET fallback if CDN signer configuration is absent
  • External application backend to Integration API: 14. [Service integration] Present permanent rms_live_* service key; key never enters frontend JavaScript
  • IntegrationService to MongoDB: 15. Parse keyId/secret, load app, require enabled state and active non-expired/non-revoked key
  • IntegrationService to Integration request context: 16. Compare HMAC-SHA256 verifier with timingSafeEqual and consume the per-minute request budget
  • Scope guard to Integration endpoint: 17. Require catalog:read, playback:create, playback:server and/or events:write according to endpoint
  • PlaybackService to Integration policy: 18. For browser mode, normalize/allowlist origin; clamp requested session TTL to app policy and global maximum
  • PlaybackService to External backend/browser: 19. Mint integration-playback-hls JWT containing appId, keyId, sessionId, trackId, optional origin/subject and eventsAllowed
  • External browser to Music API + CloudFront: 20. Use only the short-lived capability for manifests; heavy bytes still use signed media URLs
  • Music API to Integration credential state: 21. On every integration playback-token use, re-check that the referenced app/key remains active so revocation terminates old capabilities
  • Admin to IntegrationService: 22. [Key rotation] Rotate the unused primary/secondary slot and receive the new service token
  • IntegrationService to MongoDB IntegrationApp: 23. Store irreversible authentication HMAC plus AES-256-GCM encrypted reveal copy; audit later admin reveals
  • Operator to External application: 24. Deploy new slot to consuming backend, observe usage move, then revoke old slot without downtime

Four tagged flows: user authentication, first-party playback, service integration, key rotation.