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, and where it stands
Pick an operation and a format
Convert, docx → pdf. The pair resolves to a pipeline through the published routing table, not to a hardcoded handler.
Choose where it runs
Hosted (the DAG engine) or serverless (scale-to-zero). The recipe is unchanged; /me reports which surfaces are available.
Select files already uploaded
A workspace library with direct-to-storage uploads and quotas. A run takes a glob or files picked one by one.
/library · inputs.match · fileIdsSet options per step
Each step carries its own with: options, validated against the plugin catalogue. The console builds forms from the same catalogue.
Run, and watch it
One pipeline instance per file, in dependency order, with per-file and per-step progress streamed to the browser.
RunAdvancer → /runs/{id}/events (SSE)Save it as a recipe
Save a finished run as a recipe, edit it as YAML with live validation, re-run it, or drive it from an AI assistant over MCP.
/recipes · save-as-recipe · /mcpThe backend milestones (M0–M6) are done and the console is built: sign-in, library, runs with a live view, a run builder, a recipe editor, the plugin catalogue and an API/MCP page. What remains is operational — deployment manifests, a shared QA environment with an end-to-end run, and the Dynabic sign-in client. See the roadmap.
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 50+ 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.