Engineering decisions
Decision
NestJS/Mongoose decorator metadata failed in the media worker
ProposedContext
NestJS/Mongoose decorator metadata failed in the media worker
The worker previously ran TypeScript through a path that could not determine schema types such as User.email, producing CannotDetermineTypeError for decorated fields.
Rationale
NestJS/Mongoose decorator metadata failed in the media worker
Make schema field types explicit in @Prop declarations and run the worker from built NestJS JavaScript rather than relying on ambiguous runtime decorator inference.
Consequences
NestJS/Mongoose decorator metadata failed in the media worker
Slightly more verbose schema declarations, but deterministic metadata and a production-like worker entrypoint.
Decision
S3 upload failed but the UI could not explain where
ProposedContext
S3 upload failed but the UI could not explain where
A direct upload can fail because of CORS, preflight, expired signing or S3 policy details, and a generic fetch error is practically useless.
Rationale
S3 upload failed but the UI could not explain where
Use XMLHttpRequest for upload progress, parse S3 XML error Code/Message/RequestId, and emit a targeted CORS repair hint for network-level failures.
Consequences
S3 upload failed but the UI could not explain where
XHR is less fashionable than fetch, which is apparently a serious concern until one remembers that fetch still lacks universally convenient upload progress.
Decision
CloudFront signed cookies do not cross unrelated registrable domains
ProposedContext
CloudFront signed cookies do not cross unrelated registrable domains
A cookie scoped under music.rishit.co.in cannot simply authenticate a browser request to an unrelated CDN hostname if domain scoping does not match.
Rationale
CloudFront signed cookies do not cross unrelated registrable domains
Use token-proxied authorized manifests and per-object signed media URLs instead of relying on a direct-to-CDN signed-cookie mode.
Consequences
CloudFront signed cookies do not cross unrelated registrable domains
Manifest traffic touches the API, but the heavy media bytes still go directly through CDN/S3.
Decision
Serverless FFmpeg is the wrong runtime abstraction
ProposedContext
Serverless FFmpeg is the wrong runtime abstraction
Long-running polling/transcoding needs binaries, disk and lifecycle control that do not fit ordinary request functions.
Rationale
Serverless FFmpeg is the wrong runtime abstraction
Keep HTTP control plane on Vercel and deploy the transcoder as a dedicated Node 22 Alpine + FFmpeg container.
Consequences
Serverless FFmpeg is the wrong runtime abstraction
One extra runtime to operate, in exchange for not forcing a square peg through a serverless timeout-shaped hole.
Decision
External apps need browser playback without secret leakage
ProposedContext
External apps need browser playback without secret leakage
Embedding a permanent music service key in portfolio JavaScript would turn a reusable integration into a public credential.
Rationale
External apps need browser playback without secret leakage
Keep the service key on the external backend; mint short-lived track-scoped browser capabilities with optional origin binding and event permissions.
Consequences
External apps need browser playback without secret leakage
External apps need a tiny backend exchange, but credential compromise is dramatically reduced.
Decision
Prevent duplicate media processing without introducing a queue service yet
ProposedContext
Prevent duplicate media processing without introducing a queue service yet
Multiple worker instances can observe the same QUEUED document if the queue is implemented as a naive find-then-update sequence.
Rationale
Prevent duplicate media processing without introducing a queue service yet
Claim the oldest eligible track with one atomic MongoDB findOneAndUpdate that changes QUEUED -> PROCESSING and returns only the winning document.
Consequences
Prevent duplicate media processing without introducing a queue service yet
This removes the normal double-claim race with very little infrastructure, but PROCESSING is still a document state rather than a full leased job record.
Decision
A worker can die after claiming a track
ProposedContext
A worker can die after claiming a track
The current PROCESSING state has no worker owner, heartbeat or lock expiration; a hard crash after claim can leave a track stuck indefinitely.
Rationale
A worker can die after claiming a track
Document this as a known operational gap and plan a MediaJob model with workerId, attempt, lockExpiresAt, heartbeatAt and stale-job requeue/reaper behavior.
Consequences
A worker can die after claiming a track
The present implementation stays simple for a personal/private catalog, but automatic crash recovery is deliberately deferred until job leasing is introduced.
Decision
Retries need a budget once processing volume grows
ProposedContext
Retries need a budget once processing volume grows
Manual Retry can repeatedly enqueue a deterministic corrupt source or non-retryable FFmpeg failure.
Rationale
Retries need a budget once processing volume grows
Future job state should persist attempt count, classify retryable versus terminal failures, apply exponential backoff and dead-letter permanently failing work.
Consequences
Retries need a budget once processing volume grows
Manual retry is transparent and adequate at current scale, while automated retry policy adds failure taxonomy and queue-state complexity.
Decision
Keep Vercel out of the audio byte path
ProposedContext
Keep Vercel out of the audio byte path
Proxying source uploads and every HLS media segment through serverless application functions would increase bandwidth cost, latency, memory pressure and timeout exposure.
Rationale
Keep Vercel out of the audio byte path
Use the API as a control plane only: browser -> presigned S3 for ingest, API-authorized manifests for policy, then signed CloudFront/S3 URLs for media bytes.
Consequences
Keep Vercel out of the audio byte path
Authorization logic must safely rewrite manifests and manage short-lived capabilities, but application compute no longer carries large media payloads.
Decision
Preserve privacy without pretending signed delivery is DRM
ProposedContext
Preserve privacy without pretending signed delivery is DRM
Private buckets and signed URLs can enforce who may fetch media, but a browser that legitimately plays audio necessarily receives decodable media bytes.
Rationale
Preserve privacy without pretending signed delivery is DRM
Define the system explicitly as access-controlled streaming, not DRM, and reserve DRM ecosystems for future licensing requirements that truly need them.
Consequences
Preserve privacy without pretending signed delivery is DRM
The architecture remains understandable and appropriate for a private platform, while accepting that authorized clients can ultimately access played content.
Decision
Avoid path traversal becoming a signing oracle
ProposedContext
Avoid path traversal becoming a signing oracle
A rendition playlist containing ../ paths could otherwise trick the API into signing unrelated objects from the bucket.
Rationale
Avoid path traversal becoming a signing oracle
Normalize every relative URI against the rendition directory and reject any resolved key that is outside that directory before generating a signed URL.
Consequences
Avoid path traversal becoming a signing oracle
Manifest rewriting performs additional validation on every rendition request, but the signing capability stays confined to the expected HLS object subtree.
Decision
Revoke integration access before old browser tokens naturally expire
ProposedContext
Revoke integration access before old browser tokens naturally expire
A self-contained short-lived JWT could remain usable after its backing service credential has been revoked.
Rationale
Revoke integration access before old browser tokens naturally expire
Integration playback-token verification re-loads the app/key and requires the credential to remain active on use.
Consequences
Revoke integration access before old browser tokens naturally expire
Playback manifest requests incur a database credential check, but key revocation has meaningful immediate effect instead of being purely TTL-based.
Decision
Support zero-downtime service-key rotation
ProposedContext
Support zero-downtime service-key rotation
Replacing a single service key atomically across multiple deployments risks either downtime or an overlap period with unmanaged duplicate credentials.
Rationale
Support zero-downtime service-key rotation
Give each integration primary and secondary slots, rotate the unused slot, deploy it, observe usage by keyId, then revoke the previous slot.
Consequences
Support zero-downtime service-key rotation
The credential schema and admin UI are more involved than one secret field, but rotation can occur without coordinating a single exact cutover instant.
Decision
Allow admin key reveal without making the authentication database reversible
ProposedContext
Allow admin key reveal without making the authentication database reversible
An irreversible verifier is ideal for authentication, but operators may need to retrieve an active integration token after initial creation.
Rationale
Allow admin key reveal without making the authentication database reversible
Store two independent forms: HMAC secretHash for authentication and a separately AES-256-GCM encrypted token copy for authenticated admin reveal, with reveal auditing.
Consequences
Allow admin key reveal without making the authentication database reversible
There is now encrypted secret material to protect and rotate, but compromise of the ordinary verifier alone does not reveal the service token.
Decision
Large-catalog administration will outgrow client-heavy listing
ProposedContext
Large-catalog administration will outgrow client-heavy listing
Loading and filtering a practical first page of catalog records works now but becomes inefficient as artists, albums and tracks grow substantially.
Rationale
Large-catalog administration will outgrow client-heavy listing
Evolve admin listing toward indexed server-side search/filtering with cursor pagination and query-aware endpoints.
Consequences
Large-catalog administration will outgrow client-heavy listing
The current UI remains simpler for the present catalog; scaling the admin later requires more API/query design rather than premature complexity today.
Decision
Catalog deletion and media-object deletion have different failure semantics
ProposedContext
Catalog deletion and media-object deletion have different failure semantics
Deleting a MongoDB record immediately while also deleting source/HLS objects synchronously can leave either dangling records or orphaned objects when half the operation fails.
Rationale
Catalog deletion and media-object deletion have different failure semantics
Treat current record deletion and future media cleanup separately; the safer evolution is soft delete followed by asynchronous object cleanup and periodic reconciliation.
Consequences
Catalog deletion and media-object deletion have different failure semantics
Temporary orphaned storage is preferable to irreversible cross-system partial deletion, but lifecycle cleanup needs a later maintenance worker/process.
Decision
Playback events are analytics, not an exactly-once financial ledger
ProposedContext
Playback events are analytics, not an exactly-once financial ledger
Client retries, tab closure and network loss can duplicate or drop behavioral playback events.
Rationale
Playback events are analytics, not an exactly-once financial ledger
Use the current event stream for operational analytics/play counts, and add event IDs, idempotency/deduplication and a durable analytics sink only if royalties or billing ever depend on it.
Consequences
Playback events are analytics, not an exactly-once financial ledger
The current system is much simpler and sufficient for product analytics, but its counters should not be represented as billing-grade truth.
Engineering practices
• Keep application compute off the byte path — Reliability improves when heavy media delivery does not depend on the request-serving control plane.
• Make asynchronous work observable — Long-running work needs explicit lifecycle state, retry semantics and failure visibility.
• Use bounded playback capabilities — A leaked browser credential should have limited scope, lifetime and blast radius.
• Operational telemetry — Latency, failure rate, worker backlog and playback errors should be visible before users become the monitoring system.
• Shared contracts in a monorepo — Keep web, API and worker changes reviewable together while preserving runtime boundaries.
• Treat media derivatives as build artifacts — Generated artifacts should be reproducible, replaceable and separate from source masters.
• Automated delivery checks — Build, type, lint and deployment verification should gate releases consistently.