AI Content Platform

A portfolio-safe extraction of a larger private prototype: a Next.js control plane persists AI generation requests in PostgreSQL, enqueues work with Redis/BullMQ, and runs ComfyUI workflows in a separately deployable worker.

The default path is a GPU-free dry run, so reviewers can evaluate the full queue and persistence lifecycle without installing a model stack.

Architecture

flowchart LR
  UI["Next.js UI"] --> API["Idempotent API"]
  API --> DB[("PostgreSQL job state")]
  API --> Q[("Redis / BullMQ")]
  Q --> W["Generation worker"]
  W --> C["ComfyUI or dry-run adapter"]
  W --> DB

Loading

Engineering highlights

• Idempotency is enforced by a PostgreSQL unique constraint, including concurrent request races.
• BullMQ uses bounded exponential retries while PostgreSQL remains the durable status source.
• Web and worker processes scale independently and fail independently.
• The worker records attempts, start/completion timestamps, output references, and final failure reasons.
• ComfyUI is adapter-backed and opt-in; dry-run mode is safe for CI and local review.
• Zod validation, strict TypeScript, Vitest, ESLint, Docker Compose, and GitHub Actions are included.

Quick start

The complete stack runs in containers:

docker compose up --build

Open http://localhost:3000. PostgreSQL and Redis are exposed on their standard ports for inspection. The worker uses COMFYUI_DRY_RUN=true, so submitted jobs complete without a GPU.

For local development:

npm install
cp .env.example .env
docker compose up -d postgres redis
npm run db:push
npm run dev
# in a second terminal
npm run worker

On PowerShell, replace cp .env.example .env with Copy-Item .env.example .env.

API

Create a job:

curl -X POST http://localhost:3000/api/generations \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: demo-request-001" \
  -d '{"prompt":"A clean isometric cloud architecture diagram"}'

Poll GET /api/generations/{id} for durable status. Reusing the same idempotency key returns the original job.

Quality checks

npm run lint
npm run typecheck
npm test
npm run build

My contributions

• Designed the web/queue/worker separation and durable job state model.
• Implemented idempotent submission, retry-aware state transitions, and structured worker events.
• Integrated an adapter boundary for local ComfyUI workflows with a safe dry-run path.
• Added containerized local infrastructure, automated tests, CI, and technical documentation.

Tradeoffs and next steps

• This public version stores only output references; production object storage and signed delivery URLs are intentionally out of scope.
• A production deployment would add authentication, per-user quotas, OpenTelemetry traces, and a dead-letter replay interface.
• ComfyUI workflows depend on locally installed models and nodes. The checked-in file demonstrates placeholder injection and must be adapted before real generation.

See design decisions for the reasoning and failure model.

Development note

This repository was prepared from a private, domain-specific prototype and intentionally excludes its branding, user data, generated media, and sensitive business features. AI-assisted development tools were used during implementation; the architecture, code paths, and checks are documented so every decision can be reviewed and explained.