Architecture record
How Documentize Cloud works
The decisions behind documentize.cloud, and the code in this repository that already implements them.
What the cloud is
Four ways to run the same document catalogue, and one place to describe the work.
documentize.app sells tools — drop a file, get a file. documentize.ai sells AI features. Both are consumer-shaped: the page is the product, and the main control is an upload box.
documentize.cloud sells a way to run document processing. The visitor is a developer or platform engineer, and the thing they need from the site is not a converted file — it is a decision about where the work executes and how a multi-step job is described.
The unit of work is a run, not a click
A run is a recipe applied to a set of files on a chosen surface. It has progress per file and per step, it can be re-run, and it can be written as YAML instead of clicked.
Files outlive the operation
Uploads belong to a workspace, not to a task. The output of one run is available as the input of the next without a download-and-re-upload round trip.
The user journey the architecture has to serve
Pick an operation and a format
Convert, docx → pdf. The pair resolves to a pipeline, not to a hardcoded handler.
Choose where it runs
Serverless, hosted or self-host. This selects the submission target; the recipe is unchanged.
run.surface → queue selectorSelect files already uploaded
The workspace library, filtered to the formats this pipeline accepts.
needs workspace-scoped storage — see RoadmapSet options per step
The form is generated from each plugin's declared parameters, not hand-written per plugin.
[CliOption] on the plugin's options typeRun, and watch it
One DAG instance per file, executing in dependency order with live per-step progress.
DagOrchestrator → StatusReporter → RedisSave it as a recipe
The run serialises to YAML. Re-run it, edit it as text, or call it from the API and MCP.
Run → WorkflowTemplate serialiserSteps 1, 5 and 6 are the expensive parts of a document-processing cloud — pipeline execution, crash resume, backpressure, warm process pools — and they are already running code. The work ahead is concentrated in ownership and presentation, not in the engine.
The three decisions
Each has its own page, with the source that backs it.
The engine already exists
decision 01Cloud runs on the DAG orchestrator in Documentize.Plugin.Manager, with its 49 manifest-declared plugins.
Three products, one catalogue
decision 02Cloud, Serverless and Self-Host keep separate engines — so the shared document logic has to be governed deliberately.
One grammar for pipelines
decision 03A user recipe and a shipped template are the same file format, so the builder and the DSL never diverge.