AI-Powered Image Generation & Publication System (Imagetron)
Imagetron is a contract-first, workflow-driven backend system that orchestrates third-party AI image generation and publication through explicit domain modeling and asynchronous boundary management.
Contents
System Overview
Source code excerpts and engineering artifacts on GitHub.
Purpose
The system coordinates long-running image generation workflows for artists and content creators from prompt preparation to publication, maintaining internal consistency while interacting with eventually consistent third-party APIs.
Key Engineering Signals:
- Contract-first backend (OpenAPI → generated boundary → implementation)
- Explicit domain modeling (Prompts, Images, Storage, Persistence)
- Async orchestration (REST + webhook + SSE)
- External AI service lifecycle management
- Containerized deployment with CI
- 150+ automated tests, >90% coverage
Scope of Work
Client collaboration, domain exploration, requirements elicitation, domain modeling, system architecture, backend implementation, infrastructure design and setup (IaC), system delivery.
Completed
March 2025
Engineering Characteristics
Built as a private production system (no NDA), it demonstrates:
- External AI job lifecycle integration (webhook-based state transitions)
- Idempotent update handling
- Server-Sent Events streaming to frontend
- Explicit OpenAPI contract definitions
- Containerized deployment behind reverse proxy
- Observability stack (logs + dashboards)
- C4 architectural modeling and domain documentation
- Engineering execution supported by Jira (planning/tracking) and Slack (team communication)
NB: The system is no longer operational because the third-party API provider (GoAPI) discontinued its service. The case study and repository demonstrate the engineering architecture, workflow design, and implementation.
Technology Stack
- Backend: Node.js, TypeScript, Fastify, MikroORM
- API Contract: OpenAPI 3.1, JSON Schema, AJV
- Persistence: SQLite, S3
- Async Workflow: Webhook integration, Server-Sent Events
- AI: OpenAI REST API
- Testing: Vitest
- Delivery & Infrastructure: Docker, Docker Swarm, Traefik, CI/CD
- Observability: Sentry, Loki, Netdata
Engineering Decisions
-
Contract-first API: OpenAPI contract is the single source of truth, keeping implementation aligned with the contract and preventing divergence across subdomain contracts. Code uses generated contract outlet distributed as an NPM package. The contract is enforced on backend for request/response payload validation and type inheritance via JSON Schema and AJV validation.
-
Webhook + SSE Workflow: Third-party image generation is asynchronous; webhook ingests task results/progress, then the backend pushes completion state to the UI via SSE (no polling), using an internal event bus to decouple ingestion from UI delivery.
-
Subdomain Boundaries: Clear separation of Prompts vs Images domain logic, plus Ports/Adapters; keeps external integrations (GoAPI, S3, HTTP) isolated from domain behavior and makes testing/mocking straightforward.
-
Idempotency / Failure Handling: Webhook processing targets a prompt by
(prompt_uuid + task_uuid + command + expected status=Pending), so duplicate/out-of-order callbacks don’t re-apply state; state transitions and counters are updated transactionally; failures switch prompt/task to failure states and still emit a processed event for UI consistency. -
Internal Event Bus: Webhook handler emits a domain/app event; handlers persist results and emit a "processed" event; SSE listens to processed events only. This removes coupling between HTTP endpoints and long-running processing.
Failure & Reliability
-
Webhook retries / duplicates: Safe by design: duplicate callbacks won’t find a
Pendingtask match, so they effectively no-op. -
Partial image generation / partial persistence: Each image download/upload is handled independently; failures are recorded per image (
is_persisted=false,error_message), so the prompt can progress while preserving diagnostics. -
Third-party delays / progress events: "Processing" callbacks return 202 and log progress; completion triggers full processing and UI notification.
-
Atomic state transitions: Prompt/task status + active-task counter updates happen inside ORM transactions, then a single "processed" event is emitted for the UI.
-
Operational safeguards: Webhook auth middleware (secret + route check), API key middleware, Sentry error capture, structured logging, SSE heartbeat + disconnect cleanup.
Product Capabilities
- Prompt Generation: Leveraging ChatGPT, Imagetron helps an artist crafting high-quality prompts to fuel AI image creation.
- Seamless Image Generation: Integrates with Midjourney via a 3rd party REST API to generate images with zero manual action.
- Storage & Automated Upload: Temporarily stores images in S3 and automates uploading to platforms like Adobe Stock via dedicated browser extension.
- Comfortable User Interface: A Vue-based frontend lets users manage prompts and images comfortably, while backend automation handles the heavy lifting. It co-operates with the dedicated browser extension to automate image upload submissions.
General System Scheme
The scheme presents the engineering process (gray, left side) and the final application (blue, right side) as a whole, providing insight into how complex even moderate engineering endeavors can be, and how I handle the complexity in concrete products.
The engineering process is presented on the left side, is professionally structured and emphasizing approaches like decoupling, "right from the first time", zero defects, zero waste and long-term evolvability.
Unlike the wide-spread view of engineers as "coders" or "programmers," real-world applications demand far more, including requirements elicitation and specification, architecting, code modeling, infrastructure planning, and expectations around long-term product evolution.
The final system, shown on the right, implements a robust, modular composition of prompt and image services, persistence layers, a monitoring stack, and UI access points. It manages the entire lifecycle of AI-generated images - from prompt to delivery - while enabling developers to maintain quality, visibility, and operational control.
[HINT] Add the SVG Navigator extension to your Chrome to comfortably view the diagrams with zoom and pan in the separate tab.
Artist General Workflow
The following sequence illustrates the asynchronous lifecycle of an image generation request from the artist through Midjourney and back to the application via webhook and SSE.
Midjourney Image Generation Domain Overview
The diagram presents the Midjourney commands hierarchy to give you a quick grasp of the problem domain context being automated.
The diagram is taken out as-is from the actual design documents, links in the legend are just kept for brevity, not usable because leading to private repository.
Sea-Level Use Cases by DDD Subdomain
Prompts
| Use Case | Actor |
|---|---|
| Obtain Image Prompt Subjects | Artist, Backend, ChatGPT |
| Obtain Image Prompts | Artist, Backend, ChatGPT |
| [CRUD] Retrieve prompts Subjects Chat history | Artist, Backend |
| [CRUD] Remove prompts Subjects Chat history | Artist, Backend |
| [CRUD] Retrieve prompts list | Artist, Backend |
| [CRUD] Remove the prompt | Artist, Backend |
| [CRUD] Retrieve specific prompt | Artist |
| Obtain different Prompt Title | Artist, Backend, ChatGPT |
| Manage Image Prompt Manual Statuses | Artist |
Images Subdomain
| Use Case | Actor |
|---|---|
| Generate initial image versions (Imagine) | Artist, Backend, Midjourney API Intermediary |
| Regenerate image versions (Reroll) | Artist, Backend, Midjourney API Intermediary |
| Create image variations | Artist, Backend, Midjourney API Intermediary |
| Upscale selected image version | Artist, Backend, Midjourney API Intermediary |
| Handle Midjourney commands results: download generated images or process errors (webhook) | Backend (with SSE), Midjourney API Intermediary, Web Application (with SSE) |
| Retrieve images list | Artist, Backend |
The Application Architecture
[HINT] Add the SVG Navigator extension to your Chrome to comfortably view the diagrams with zoom and pan in the separate tab.
The following C4 container diagram provides a high-level architectural blueprint, focusing on key system components and their interactions to guide both technical and non-technical stakeholders during design, implementation and evolvement phases.
During the design phase, it allows engineering team to visualize component relationships before implementation, aligns non-technical stakeholders on system scope and external integrations, identify potential bottlenecks (e.g., reliance on external APIs like Midjourney/Adobe Stock).
In implementation phase this diagram serves for engineers as a foundational reference for structuring code repositories, separating modules, and defining critical interface contracts.
The diagram acts as a living artifact that bridges conceptual design with practical implementation, ensuring consistency as the system evolves.
Models
[HINT] Add the SVG Navigator extension to your Chrome to comfortably view the diagrams with zoom and pan in the separate tab.
Here are a the examples of a multiple engineering models I created to decompose domain and system complexity, enabling straightforward coding and further system evolution through professional modularization and decoupling.
Prompt State Diagram
The core system behavior flow - the prompt states that dictate dependent objects' behaviors.