processOS documentation

Workflows defined as templates, run as processes, driven by human input, branching logic, background jobs, and external integrations.

Quickstart

Commands here run from the repository root. Root wrappers preserve the root .env and .process-platform operational location while targeting applications/main. Running directly inside applications/main instead uses that working directory for environment/data defaults; do not accidentally point the web and worker at different stores.

Auth0 is required for this path. File storage is used when MONGO_URL is unset. Without Auth0, npm run qa:local runs every app offline with synthetic seats; see offline local development.

npm install

# Fill Auth0 + app URLs from applications/main/.env.example — see operations/auth0-setup.md
cp applications/main/.env.example .env

npm run dev:all          # Next + the step worker

Open http://localhost:3000 and sign in. Data lands in .process-platform/ unless MONGO_URL is set.

Use npm run dev:all, not npm run dev — without the worker, input is the only step type that advances and every run parks on the first automated step.

Detail: installation. Stuck: troubleshooting.

Start here

New to the codebase? Installation → How it works → Your first process

Need a specific fact? Jump to reference, or the glossary.

Something is broken? Troubleshooting.

Changing something? Start with the current architecture status, then find the relevant guide. Run the verification gate and follow the project boundaries.

Getting started


Installation	Local setup, Auth0 configuration, and storage choices.
How it works	The shape of the system. Read this one first.
Your first process	Start a run and drive it to completion, one API call at a time.

Concepts


Templates	The recipe, and why a running process ignores yours.
Processes	One run — instances, context, the audit trail.
Steps	The chain, human vs automated, failure contracts.
Roles and groups	Users, organizations, roles, impersonation.
The process engine	How a run advances, and the worker that drives it.
Storage	Canonical repositories, explicit drivers, and what is persisted.

Features


Dashboard and lists	The screens you land on before opening anything.
Template viewer	Read-only view of a published template — the step list, its settings, and the runner preview. Templates are defined in code.
Process runner	Where a run happens — forms, steps, completion.
Sharing	How to give someone access to one run.
Records	The archive of finished runs, and what it surfaces that nothing else does.
Document database	Global collections of JSON documents, plus read/write process steps.
Audit and export	How to read what a finished run actually did.
Whitelabel	How one app serves several branded front doors.

Operations


Deployment	N web services, exactly one worker.
Closed-runtime cutover	Migration, configuration, activation order, and rollback.
MongoDB replica set	Converting a standalone MongoDB to a single-node replica set, which template publication needs.
Dependency security	Patched runtime dependencies and scoped development-only findings.
Auth0 setup	What to configure so permissions actually reach the app.
Troubleshooting	Symptoms, in the words you would use before you know the cause.
Known issues	Every known defect, and where the fix goes.

Reference


Step types	All 15, with real examples and how each one fails.
Field types	All 11, plus the modifiers any field can take.
Choice lists	Fixed dropdown values, and lists computed by a recipe (checked again when a value is written).
Permissions	The permission strings, enforced at three levels.
Expressions	The six slots, what is in scope, and the helpers.
Environment	The minimum that runs, then every variable.
Glossary	One definition per term, and the six words that mean two things.
API reference	Swagger UI at `/docs/api` in the running app, from `applications/main/src/lib/openapi.ts`.

Guides


Author a template	Editor vs repo file, and the decisions to make.
Add a step type	The 9-file checklist.
Add an integration	Failure contracts, credentials, preconditions.
Add a skin	Branding and navigation per deploy.
Add an API route	Handlers and permission gates.
Manage templates	Moving templates between the repo and the database.
Develop against prod data	Copying the production database locally, safely.
Offline local development	`npm run qa:local`: every app offline with synthetic seats, plus agent acceptance checklists.

Six things that surprise people

A process snapshots its template at start. Editing a template does not change runs in flight.
Steps are a linked list, not an array. Order comes from nextStepKey; array order means nothing.
input is the only step type a user advances. Everything else needs the worker — npm run dev alone will leave runs parked.
Failure is not one behavior. 5 types stop the run, notifications record the failure and continue, and 6 can throw — which the worker logs and retries every second, forever. See failure contracts.
A skin is not a security boundary. Hiding a route from the sidebar does not block the URL. Backend identity, permission and process-sharing checks enforce access.
Shipped templates are gap-filled on read. Missing keys from applications/main/src/templates/registry.ts are inserted on getTemplate / listTemplates; existing storage copies are not overwritten. Force-rewrite with manage templates.

Conventions

Defects live in one place. Every page ends with a Known gaps section linking into known issues. A fix updates one document.

⚠️ inline means acting without knowing causes harm — the one-worker rule, the closed-source guard, expanding subroutines before comparing templates. Everything else is a known gap, not a warning.

The source code wins. If a document and the implementation disagree, the code is right — fix the document in the same change that exposes the disagreement.

npm run check:docs enforces what can be checked mechanically: structure, house style, cross-links, heading anchors, cited file paths, and counts asserted in prose against the code. It cannot tell you a sentence is wrong, only that a fact is.