Architecture
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 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 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.