Workflow Manager: what the repo is, and how it works

I recently had to explain my workflowmanager repository to someone who had never seen it before, and that turned out to be harder than it should have been.

The repository has a README, and the README is still useful, but it captures an earlier snapshot of the project. Since then the repo has become broader, cleaner, and more product-shaped. So instead of writing yet another note about “what changed,” I wanted one post that simply explains the repository as it exists today: what problem it is solving, what each part is responsible for, and how the pieces fit together.

Summary

At a high level, workflowmanager is a system for running AI-assisted workflows where the machine does a lot of the work, but a person stays inside the loop.

The repository contains the execution engine, the APIs that expose it, the worker that handles long-running jobs, the interfaces people use to run workflows, and the editor used to design and preview them. It is not just “an AI app” and it is not just “a workflow runner.” It is closer to a workflow platform built around event-sourced execution, modular steps, and a strong separation between production runs, safe preview runs, and public demo runs.

The shortest accurate summary is this: workflowmanager is a repo for defining content-generation workflows, executing them against real or virtual backends, and giving both operators and authors a UI around the whole process.

Start with the problem the repo is trying to solve

The easiest way to misunderstand this project is to begin with the folder tree.

The real starting point is the kind of work it is trying to support. The workflows in this repo are not generic business-process automation. They are oriented around AI-assisted content creation: collecting inputs, generating structured prompts, asking a user to select or refine options, kicking off image or video generation, analyzing results, producing text overlays and titles, and assembling a durable record of how that run unfolded.

That kind of work has two competing requirements.

On one side, you want automation. You want models, templates, provider integrations, and background workers to keep things moving without constant manual effort. On the other side, you do not actually want a black box. You need to inspect state, pause for user decisions, review generated outputs, resume runs, and understand why a workflow produced what it produced.

workflowmanager is the shape the repo takes when you try to satisfy both requirements at once.

The core of the system is an event-sourced workflow engine

Everything else in the repository makes more sense once the execution model is clear.

A workflow is defined as a sequence of steps. Each step contains one or more modules. Those modules can do very different kinds of work: collect user input, call an LLM, transform structured data, queue media generation, analyze generated content, or ask a person to make a choice before the run can continue.

As the workflow runs, the system keeps writing down what happened. That is the event-sourced part.

Instead of treating execution as a transient request that either succeeds or fails, the platform records state transitions, interaction points, outputs, and progress in MongoDB. That gives the frontend something to stream, gives operators something to inspect later, and gives the backend enough history to reconstruct what happened without guessing. It also fits the real nature of these workflows: they are often long-running, interactive, and dependent on external services that do not behave like a simple synchronous function call.

This is why the README’s original framing still holds up. The repo is still fundamentally organized around an event trail, modular execution, and human-in-the-loop control. The rest of the repository exists to make that model useful in more contexts.

backend/workflow_engine is now the real center of gravity

One of the biggest ways the repository has matured is that the engine has been pulled out into its own backend package.

That matters more than it sounds. In an earlier shape, it was easy to think of the project as “the server, plus some workflow code inside it.” The current repo is cleaner than that. The core execution logic lives under backend/workflow_engine, which is where the models, modules, orchestration logic, workflow services, and supporting utilities now live.

That gives the whole system a better boundary.

The engine is where the domain lives. It is where workflow definitions are interpreted, module execution is coordinated, and shared use cases are expressed. The surrounding servers are no longer the place where the workflow system is invented; they are the places where the workflow system is exposed.

You can see that in shared use cases like workflow start. The project now has policy-driven orchestration that can be reused by different API layers while still letting each server decide what “start a workflow” means in its own context. That is a strong sign that the repo is no longer organized around one entrypoint. It is organized around a reusable core.

The backend is really several execution surfaces around the same engine

Once the engine is separated properly, the rest of the backend structure becomes much easier to explain.

backend/server is the main production API. This is the part that handles the normal application concerns: authenticated access, workflow lifecycle endpoints, state retrieval, event streaming, and the regular path for running the system as an actual product.

backend/worker is the asynchronous side of that same world. It exists because a lot of the interesting work in these workflows should not happen inline with an HTTP request. Media generation is the obvious case. If a step needs to ask an external provider to create an image, audio asset, or similar output, the workflow can hand that job to the queue and let the worker process it separately. That keeps the main execution flow responsive while still folding the result back into the event-sourced state model.

Then there is backend/virtual_server, which is where the repo starts to feel more specialized.

This server is not just a second copy of the main API. It exists to run workflows in an isolated virtual environment with its own data boundary. That makes preview execution a first-class capability. A workflow author or editor can exercise part of a flow, inspect intermediate state, and experiment without contaminating production state or pretending that preview logic is the same thing as a live run.

And finally there is backend/landing_virtual_server, which is even more opinionated. This service exists to back the public-facing product demo and landing experience. It gives the repository a place to expose curated workflow behavior for storytelling and onboarding without opening the full product surface.

That four-part shape tells you a lot about the repo today. It is no longer “an app server with helpers.” It is a workflow engine surrounded by different execution contexts: one for the real product, one for asynchronous work, one for safe preview, and one for public demonstration.

The data layer is designed for inspection as much as storage

A lot of AI systems treat persistence as an afterthought. This repo does not.

The MongoDB layer under backend/db is not just a place to throw documents after the fact. It is part of the design. Repositories, migrations, and the custom Mongo-backed task queue are all there because the system needs durable workflow state, event history, user records, content blobs, and references to generated media.

There is also an important split between what lives in MongoDB and what lives on disk. Small structured content, workflow state, and event records live in the database. Generated media assets live in the filesystem, with the database storing the references that tie those assets back to workflow state.

That is a practical choice, but it also says something about the repo’s priorities. This is not just storing outputs. It is storing an execution history that the rest of the system can reason about.

The workflow definitions are where the repo becomes concrete

If backend/workflow_engine is the heart of the system, the workflows/ directory is where the repo stops being abstract.

The current workflows under workflows/cc and workflows/oms show the actual domain the system is built for. These are not placeholder samples. They describe real multi-step content pipelines with stages for user input, prompt generation, image analysis, video generation, music generation, text overlays, titles, and summaries.

That is important because it keeps the project honest. A lot of systems call themselves “workflow engines” but only prove that they can move JSON around. This repo demonstrates the opposite. The workflows reveal what kinds of decisions the platform needs to support, which modules need to exist, where user intervention matters, and why the event-sourced model is useful.

They also show how the project has matured. The newer media generation path is not just a thin call out to a provider. It has a richer contract around prompt generation, provider-specific configuration, structured results, and previewability. That makes the workflows easier to author, easier to test in a virtual environment, and easier to represent consistently in the editor.

In other words, the workflow files are not passive configuration. They are the clearest expression of what the platform is actually for.

The web UI is not just a frontend for results

The original README described a web client, a terminal UI, and a status monitor. That is still directionally true, but the current repo’s frontend story is more interesting than “there are several clients.”

ui/webui is the main runtime product. It is where a user can start workflows, respond to interactions, follow execution progress, and move through the normal application flow. But it also carries much more of the outer product now: authentication flows, invitation handling, guidance, landing pages, and a demo experience wired into the landing virtual API.

That last part matters because it means the web application is not only an operator console. It is also part of the product narrative. The repo now includes the experience of showing the system to new users, not just the experience of using it after login.

There are still secondary interfaces too. The terminal UI and status tooling continue to make sense as operational surfaces, especially for quick inspection or headless workflows. They reinforce the broader point that the system’s protocol is not tied to one presentation layer.

The editor changes the meaning of the whole repository

The biggest frontend addition is ui/editor, because it changes what the project is.

Without the editor, this repository is a workflow runtime with a few ways to trigger and observe it. With the editor, it becomes a workflow authoring system.

The editor is built around a visual graph view of workflows and step/module structure. But the more important part is what sits behind that graph: module-aware editing controls, workflow JSON inspection, schema-driven inputs, clone/template flows, and virtual execution tooling that can preview behavior against the current draft. It is not just drawing boxes. It is trying to make workflows understandable and editable as living objects.

That is also why the virtual runtime work under ui/shared/src/virtual-runtime matters. Preview execution is not buried as editor-specific glue. It has been extracted into shared client infrastructure so the idea of “run this safely in a virtual environment and inspect the result” becomes a real capability of the platform, not a one-off convenience feature.

This is the point where the repository stops looking like a single application and starts looking like a platform with both runtime and authoring layers.

The provider layer and worker model exist to keep the engine modular

Another important part of the repo is the line between the engine and the outside world.

The provider integrations under backend/providers hide the ugly parts of talking to external AI services. The engine should not need to know the details of Leonardo, OpenAI image generation, MidJourney, ElevenLabs, or local Stable Diffusion plumbing. It should only need to express the kind of work it wants done.

The worker completes that picture. Some modules can run inline. Others need a queue, polling, retries, and background recovery. By isolating provider-specific work and asynchronous execution behind clear layers, the repo can keep its workflow model modular instead of baking every external API assumption directly into the engine.

That is one reason the architecture has held up while the project has grown. The system has room to add new module behaviors and new providers without redesigning the execution model every time.

Deployment and operations are now part of the repo’s real story

One of the easiest mistakes to make when reading the repo is to focus only on the engine and the UI and ignore the operational layers. But the deployment setup says a lot about what the project has become.

The deploy/ folder now assumes a world with multiple public-facing surfaces: the main web UI, the production API, the editor-facing virtual API, and the landing demo API. There are dedicated Dockerfiles, environment conventions, Nginx routing expectations, backup scripts, and deployment entrypoints around that arrangement.

That may not sound exciting, but it is a strong signal. It means the repository is being shaped not only to be correct, but to be run. The same is true of invitation flows, usage accounting, environment validation, and the more explicit boundaries between real execution and demo execution. Those are product and operational concerns, and they now have a visible place in the codebase.

The simplest way to describe the repo today

If I had to explain workflowmanager to a first-time reader in one pass, I would say this:

It is a platform for AI-assisted content workflows where execution is durable, inspectable, and interactive. The engine lives in backend/workflow_engine. Production runs happen through backend/server. Background provider work happens in backend/worker. Safe previews happen through backend/virtual_server. Public demos happen through backend/landing_virtual_server. The actual workflow logic is expressed in the workflows/ definitions. ui/webui is the runtime product, ui/editor is the authoring product, and ui/shared holds the client-side primitives that keep those experiences aligned.

That is the whole repo in one paragraph.

Closing thought

What I like about the current shape of the repository is that it did not abandon its original idea. It simply built the missing layers around it.

The event-sourced workflow model is still the core. Modules still define the behavior of steps. Human interaction still matters. But the repo now has better boundaries, a real authoring story, a safer preview story, and a clearer distinction between operating the system, editing the system, and demonstrating the system.

So this is the best way I know to describe it now: workflowmanager is a workflow engine, an execution platform, and an authoring environment living in one repository, all built around the idea that AI workflows should be observable and steerable rather than opaque.