Lens / Rishit Music — Private Audio Streaming Platform

Implementation notes

Low-level components

• AppModule — Composes configuration, MongoDB, storage, auth, catalog, playlists, media, integrations, playback and admin modules.

• AuthModule — Login/JWT issuance and bearer-token authentication.

• CatalogModule — Public/listener catalog reads for artists, albums and tracks.

• PlaylistsModule — Owned playlist CRUD and ordered embedded playlist items.

• MediaService — Authorize source upload, verify completed S3 object, queue processing and retry failed work.

• MediaProcessorService — Claim one queued track, run FFprobe/FFmpeg, upload output tree and commit READY or FAILED.

• Media Worker Runtime — Continuously poll for queued work, invoke MediaProcessorService and shut down on SIGINT/SIGTERM.

• StorageService — Central S3 abstraction for presigned PUT/GET, HEAD, text reads, object upload and streaming downloads to worker disk.

• PlaybackService — Authorize playable tracks, mint short-lived HLS JWTs, rewrite master/rendition playlists, sign media URLs and record playback events.

• IntegrationModule — Service-to-service authentication, scopes, key lifecycle, allowed origins, rate limits, usage metering and browser session creation.

• AdminModule — Protected administration APIs and operational summaries.

• PlayerDock — Persistent HTMLAudioElement + hls.js lifecycle, transport UI, seek/buffer/volume synchronization, queue navigation, Media Session metadata and bounded HLS recovery.

• uploadToS3 — Perform direct XHR PUT so actual byte progress is available, surface S3 XML error details and classify likely CORS/network failures.

• Admin Catalog Workspace — Single administration surface for artist/album/track metadata, pipeline visibility, WAV upload, publication, rendition/storage inspection, retry and playback verification.

• Direct S3 Upload Client — Uploads source WAV bytes directly from the browser to a one-object presigned PUT while exposing byte-accurate progress and actionable S3 errors.

• Persistent PlayerDock — Owns the HTMLAudioElement/HLS.js attachment lifecycle, asks the API for short-lived sessions, synchronizes playback state and performs bounded media/network recovery.

• Player Store — Client-side playback state shared across navigation so queue, active track, timing, buffering and volume survive page changes.

• Integration Policy Engine — Authenticates external application credentials and derives an immutable request context containing app identity, key identity, scopes, origins, session TTL and rate policy.

• Integration Key Lifecycle — Supports primary/secondary service-key slots for zero-downtime rotation, authenticated reveal of supported active keys, revocation, expiry and reveal auditing.

• Integration Usage / Rate Buckets — Maintains minute-level request and playback counters used for per-integration throttling and usage reporting, with automatic TTL expiry.

• Environment Validation — Fails startup early when required database, auth, storage or media configuration is invalid instead of discovering configuration drift during a user request or transcode.

• OpenAPI + Scalar Documentation — Documents catalog, playlist, ingest, playback, integration and administration HTTP contracts for local development and external integration work.

Data model

• User: _id, email, passwordHash, displayName, roles, isActive, lastLoginAt

• Artist: _id, name, slug, bio, imageUrl, verified

• Album: _id, title, slug, primaryArtistId, artistIds, type, releaseDate, coverUrl, trackCount, durationMs, published

• Track: _id, title, slug, albumId, primaryArtistId, artistIds, trackNumber, discNumber, explicit, genres, status, sourceKey, masterPlaylistKey, renditions, sourceSizeBytes, processedSizeBytes, durationMs, processingError, processingStartedAt, processedAt, published, playCount

• Playlist: _id, name, description, ownerId, visibility, coverUrl, items, trackCount, durationMs

• PlaybackEvent: _id, userId, integrationAppId, integrationKeyId, source, externalSubject, trackId, type, positionMs, sessionId

• IntegrationApp: _id, name, slug, enabled, allowedOrigins, scopes, sessionTtlSeconds, rateLimitPerMinute, keys

• IntegrationUsageBucket: _id, appId, keyId, minute, requests, sessions, masterRequests, playlistRequests, events, playbackStarts, expiresAt

• MediaRendition: label, bitrate, playlistKey, sizeBytes, codec

• PlaylistItem: trackId, addedAt, addedBy

• IntegrationKey: keyId, slot, secretHash, encryptedToken, lastFour, createdAt, expiresAt, revokedAt, lastUsedAt, revealCount, lastRevealedAt, lastRevealedBy

Deployment

• Production web: music.rishit.co.in on Vercel.

• Production API: api.music.rishit.co.in on Vercel.

• Production media: media.music.rishit.co.in on CloudFront; this hostname is not a Vercel project.

• The media worker is deliberately persistent compute because polling + FFmpeg + local work directories do not fit ordinary request-scoped serverless functions.

• Dockerfile.worker builds @music/api on node:22-alpine and installs ffmpeg + ca-certificates in the runtime stage.

• API and worker share MongoDB media state but the worker boots a dedicated Nest application context rather than the complete HTTP AppModule.

• The restricted AWS source credential may be used as master credentials for STS AssumeRole; the assumed backend role owns actual S3 object permissions.

• If an S3 failure identifies the source IAM user rather than an assumed-role session, configuration/role loading should be repaired instead of granting the user direct bucket access.

• Source WAVs remain private under uploads/source/*; listener derivatives are generated under streams/*.

• Heavy upload bytes go directly browser -> S3 and playback segment bytes go browser -> CloudFront/S3, keeping Vercel in the control path instead of the media-byte path.

Milestones

• Control plane & catalog — Catalog, auth, playlists and media state are implemented behind a modular NestJS API.

• Private media pipeline — Direct master upload, persistent FFmpeg processing and protected HLS delivery are part of the current architecture.

• Ecosystem integrations — The active work is turning the service into a reusable capability for portfolio surfaces and external applications.

Key source files

• Root NestJS composition (apps/api/src/app.module.ts) The API is intentionally modular; the worker has a smaller dedicated application context.

• Direct upload authorization (apps/api/src/media/media.service.ts) The API never receives the WAV bytes.

• Upload verification and queue transition (apps/api/src/media/media.service.ts) Queueing occurs only after storage verifies that the source object exists.

• Atomic worker claim (apps/api/src/media/media-processor.service.ts) This is the current queue/claim primitive. It prevents the ordinary double-claim race, but it is not yet a leased job system.

• AAC fMP4 HLS generation (apps/api/src/media/media-processor.service.ts) Default rendition config is 64/128/256 kbps with six-second segments.

• Assume-role S3 client (apps/api/src/storage/storage.service.ts) The restricted source user can be used to assume the backend role instead of receiving direct object permission.

• Track-scoped playback capability (apps/api/src/playback/playback.service.ts) Playback authorization is deliberately different from the user's general JWT.

• Safe rendition path rewrite (apps/api/src/playback/playback.service.ts) A malformed playlist cannot use ../ to make the signer authorize an unrelated object.

• CloudFront signed URL with S3 fallback (apps/api/src/playback/playback.service.ts) Loss of CDN signing configuration does not require making objects public.

• Byte-accurate direct upload progress (apps/web/lib/s3-upload.ts) The progress bar measures the actual browser-to-S3 transfer rather than pretending an API request is upload progress.

• Bounded HLS recovery (apps/web/components/player/player-dock.tsx) Recovery is bounded so a permanently broken stream does not loop forever.

• Integration credential schema (apps/api/src/integrations/integration.schemas.ts) Authentication and admin reveal are separate: irreversible verifier for auth, encrypted copy only where reveal is supported.

• Graceful persistent worker loop (apps/api/src/workers/media.worker.ts) The process stops polling after SIGTERM/SIGINT and closes only after the current processNext invocation returns, avoiding intentional mid-job termination during normal shutdown.

• Timing-safe integration credential verification (apps/api/src/integrations/integration.service.ts) The persistent token is not compared as plaintext. Authentication uses an HMAC-derived verifier and timing-safe equality.

• Minute-bucket integration rate limiting (apps/api/src/integrations/integration.service.ts) The same minute buckets support both throttling and operational usage reporting; a TTL index removes old buckets automatically.

• Revealable integration secret kept separate from authentication verifier (apps/api/src/integrations/integration.service.ts) Admin reveal uses a separately encrypted full token with versioned AAD. The HMAC secretHash remains the verifier used for normal authentication.