Presentation
HTTP, SSE, UI, controllersNext.js feature modules and Express controllers translate product actions into use-case requests. Composition stays outside the domain.
presentation/controllers · routes · factories01Compose
KalpanaAI · Founder case study
One idea.
One production workspace.
Choose the format, voice, and visual language. The system turns that intent into a reviewable video project—not one opaque AI request.
WHAT SHOULD THE VIDEO EXPLAIN?Why do distributed systems fail in surprising ways?
02Review before render
The work stays
visible.
Five reader-facing phases. One project moves forward without hiding the decisions.
The product streams a scene-based script, verifies claims, generates voice and visual direction, reveals scene previews progressively, then lets the creator edit and approve the composition before rendering.
03Recover
Pull the process.
Keep the work.
The worker is temporary. The project state is not.
When a code-generation worker fails at stage seven, PostgreSQL retains the current stage and completed artifacts. BullMQ retries that stage, and buffered events help a reconnecting browser catch up before returning to live progress.
PROCESS LOST
↓
POSTGRES CHECKPOINTStage 07 + completed artifacts remain
↓
NEW WORKERResume code generation
04Validate
Code is a proposal.
Not permission.
Every scene crosses explicit gates before it joins the video.
All generated scene code is compiled with esbuild and inspected for known hazards. MCP client scene submissions additionally render the first, middle, and final frame in an isolated worker thread with a five-second timeout.
05Preview · edit · render
The creator sees
the real composition.
Chat on the left. Remotion player in the center. Scene controls and timeline around it.
RENDERED · MP4 READY
From one prompt to an editable, recoverable production workspace.
Open live productOptional technical depth
Under
the hood.
Open the appendix for exact architecture, reliability mechanisms, tradeoffs, and the evidence boundary. The main story stays focused on how the product feels and behaves.
Open architecture and decision record
300+repository commitsCurrent branch history
04architecture layersDependencies point inward
10mworker lockFor long media stages
03smoke-test framesMCP scene submissions
A / ArchitectureFour layers.
Four layers.
One protected workflow.
Application
Use cases and orchestrationUse cases coordinate repositories, queues, model ports, storage, and streaming while returning explicit Result values instead of using exceptions for control flow.
application/use-cases · interfaces · servicesDomain
Rules, state, invariantsPipelineJob owns legal stage transitions, artifact guards, progress state, and failure state. Infrastructure cannot redefine the workflow's business rules.
PipelineJob.transitionTo() · markFailed()Infrastructure
Providers and persistencePrisma, BullMQ, Redis, model providers, TTS, object storage, Remotion, and FFmpeg sit behind interfaces and are wired at explicit composition roots.
repositories · workers · service adaptersB / ReliabilityFailure is bounded,
Failure is bounded,
not denied.
Checkpoint the work, not just the status
PostgreSQL stores the current stage plus scripts, fact-check reports, audio, transcripts, directions, generated code, edit state, and rendered asset paths. A job can be understood from durable state rather than process memory.
PostgreSQL · PrismaRetry according to stage semantics
BullMQ applies explicit exponential backoff by stage. Model-heavy steps receive multiple attempts; deterministic mapping and rendering are not blindly retried. Failed jobs can be cleared and resumed from their current stage.
BullMQ · RedisReplay progress after a disconnect
Workers publish live SSE progress through Redis pub/sub. Scene-generation events are also appended to a Redis list and marked complete with a TTL, allowing reconnecting clients to replay buffered progress.
SSE · Redis bufferDo not leave the interface spinning forever
A worker-level failure listener checks non-terminal pipeline state, persists a failure, and emits a final progress event. Long media stages use a ten-minute lock with stalled-job checks.
Failure safety netTreat generated code as untrusted input
Generated JSX is compiled with esbuild, checked for known Remotion and runtime hazards, and rejected with targeted repair hints before it reaches a final render.
esbuild · static gatesBound runtime validation
MCP client scene submissions are transformed and rendered at the first, middle, and final frame in a separate worker thread. A five-second timeout terminates runaway computation without blocking the API event loop.
Worker threads · 5s ceilingC / Decision recordExplicit choices.
Explicit choices.
Visible tradeoffs.
A state machine over a giant request
- Context
- Video generation crosses slow model calls, speech services, asset storage, code execution, and headless rendering.
- Decision
- Model the product as durable stages owned by a domain entity and execute processing stages through a queue.
- Tradeoff
- More operational machinery and transition rules, in exchange for resumability, visibility, and isolated failure.
Human review before expensive production
- Context
- A fluent script can still be wrong, off-brand, or simply not what the creator wants. Downstream audio and rendering amplify that mistake.
- Decision
- Fact-check generated claims, then pause for script approval; pause again at browser preview before export.
- Tradeoff
- The flow is not fully autonomous, but user judgment is applied where it prevents the most wasted work.
Provider routing per responsibility
- Context
- Script writing, fact checking, direction, code repair, transcription, and voice generation have different model needs and cost profiles.
- Decision
- Resolve models by named agent through a ModelRegistry and place TTS, transcription, storage, and image lookup behind ports.
- Tradeoff
- Configuration becomes a system of its own, but provider changes no longer require rewriting the workflow or domain.
Share contracts with client-driven AI
- Context
- An MCP client can provide its own reasoning model, but bypassing server constraints would create a second, lower-quality pipeline.
- Decision
- Let client-driven jobs submit scripts, directions, and scene code through the same schemas, validation rules, composition logic, and persisted state.
- Tradeoff
- The protocol is more involved, but the server retains product invariants while the client supplies the intelligence.
D / Evidence boundaryCredibility includes
Credibility includes
what is not claimed.
Repository demonstrates
- A real multi-application product with domain boundaries and explicit composition roots
- Persistent workflow state, queued execution, replayable progress, and stage-aware recovery
- Generated-code validation built from observed failure modes rather than a generic AI wrapper
- Continuous product evolution across UI, media infrastructure, AI providers, auth, observability, and deployment
Not claimed without product data
- Production throughput, uptime, revenue, or user adoption
- A universal success-rate or quality benchmark
- That every commit was authored manually or by one identity
- Independent source inspection while the application repository remains private
- That every workflow follows one fixed number of stages