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.