SOPFlow

Context and ownership

SOPFlow is an open-source TypeScript toolkit for structured Standard Operating Procedures. I own the domain model and package architecture across the core workflow engine, deterministic diagram projection, React editing components, and the integration playground.

The current workspace is organized around reusable packages rather than one thesis application:

@sopflow/core
    ↓
@sopflow/diagram
    ↓
@sopflow/react

apps/playground
    └── integration consumer

Core owns workflow truth

@sopflow/core is framework-agnostic. It does not depend on React, a browser, a database, or an AI provider.

The package owns:

• runtime schema parsing;
• semantic workflow validation;
• immutable actor and step operations;
• validated operation batches;
• graph traversal and presentation helpers;
• undo/redo history;
• stable domain error codes.

A valid SOP must have one start, at least one end, valid actor and edge references, unique IDs, every step reachable from the start, and every non-end step able to reach an end.

That means consumers cannot silently create a diagram that the domain model considers invalid.

Steps are data, not execution order

The document stores steps as a collection. Their array position is not treated as workflow execution order.

Graph relationships determine topology, while helpers such as getOrderedSteps() derive a presentation order for editors and renderers.

This separation matters because authoring order, visual layout, and actual workflow edges are different concerns.

Diagram projection stays deterministic

@sopflow/diagram consumes the shared workflow model and builds deterministic diagram structures.

The package covers workflow projection, node/edge layout, routing, BPMN-style models, formal SOP flowcharts, pagination, SVG render models, labels, and path editing.

Keeping this layer separate means diagram code cannot redefine business validity.

React is an adapter over the packages

@sopflow/react composes editor and visualization components on top of core and diagram.

The React layer handles interaction and controlled UI state, while workflow mutation still flows through shared operations and invariants. Tests cover editor history, actor/step fields, deletion constraints, diagram behavior, procedure rendering, and the package public API.

Result

SOPFlow now exists as reusable package infrastructure rather than a single application-specific workflow implementation.

The main engineering lesson is: when multiple editors and renderers need the same workflow, topology and invariants should live below the UI so every consumer operates on the same truth.