Flowspine

TypeScript-first toolkit for describing business flows in code.

Flowspine helps make process structure explicit without turning your codebase into a hidden maze of controllers, services, jobs, and side effects.

It is built around four packages:

• @flowspine/core - define process topology and step contracts
• @flowspine/extractor - statically extract Flowspine DSL from source files
• @flowspine/cli - build, validate, export, and watch Flowspine catalogs
• @flowspine/viewer - embeddable React UI for browsing Flowspine catalogs

What Flowspine Is

Flowspine is a developer tool for:

• describing business flows as explicit graphs
• defining step-level execution contracts
• extracting process structure from code
• validating graph integrity
• exporting machine-readable and visual representations

Flowspine is not a workflow engine.

It does not orchestrate full graph execution automatically.

Package Overview

@flowspine/core

Use core when you need to:

• define a process with defineProcess(...)
• define a step with defineStep(...)
• execute a single step with runStep(...)
• model business flow meaning directly in code

This is the semantic layer of Flowspine.

@flowspine/extractor

Use extractor when you need to:

• scan Flowspine process files
• extract process structure programmatically
• build custom tooling on top of the DSL
• analyze repository process definitions as data

This is the static analysis layer.

@flowspine/cli

Use cli when you need to:

• scaffold a project
• build a catalog
• validate graph structure
• export JSON or Mermaid output
• watch process files during development

This is the operational layer.

@flowspine/viewer

Use viewer when you need to:

• embed an interactive catalog viewer in a React app
• inspect nodes, edges, outcomes, and branch structure visually
• use live updates against a generated catalog.json

This is the visualization layer.

Recommended Mental Model

Flowspine has four concerns:

• meaning -> @flowspine/core
• reading code as data -> @flowspine/extractor
• repository workflows -> @flowspine/cli
• catalog visualization -> @flowspine/viewer

In most real tasks:

• define or edit flows with core
• verify them with cli
• inspect them with viewer when visual review is needed

Use extractor directly only when building custom tooling or analysis.

Typical Workflow

1. Define process topology

Use defineProcess(...) to describe the flow graph:

• steps
• branches
• events
• actions
• links
• start/end structure

2. Define executable steps

Use defineStep(...) to define step contracts and behavior:

• input validation
• output validation
• allowed outcomes
• handler execution
• retry / timeout behavior

Use runStep(...) to execute a single step safely.

3. Build a catalog

Use @flowspine/cli to scan process files and generate a catalog.

4. Validate structure

Run CLI validation to catch:

• duplicate process IDs
• missing start/end nodes
• broken edges
• unreachable nodes
• weak branch fanout

5. Export graph output

Export JSON or Mermaid when needed.

Example: Process Topology

import { defineProcess } from "@flowspine/core";

export default defineProcess("order-flow", ({ step, branch, event, start, end, link, when }) => {
  const validateOrder = step("ValidateOrder");
  const paymentRequired = branch("PaymentRequired");
  const orderConfirmed = event("OrderConfirmed");
  const orderRejected = event("OrderRejected");

  start(validateOrder);
  link(validateOrder, paymentRequired);
  link(when(paymentRequired, "yes"), orderConfirmed);
  link(when(paymentRequired, "no"), orderRejected);
  end(orderConfirmed);
  end(orderRejected);
});

Example: Step Contract

import { defineStep, runStep } from "@flowspine/core";

const ValidateOrder = defineStep({
  id: "ValidateOrder",
  validateInput: (v): v is { orderId: string; itemsCount: number } =>
    Boolean(v && typeof v === "object" && typeof (v as { orderId?: unknown }).orderId === "string"),
  validateOutput: (v): v is { orderId: string; valid: boolean } =>
    Boolean(v && typeof v === "object" && typeof (v as { orderId?: unknown }).orderId === "string"),
  allowedOutcomes: ["success", "invalid_order"] as const,
  handler: async (input) => {
    if (input.itemsCount <= 0) {
      return {
        outcome: "invalid_order",
        output: { orderId: input.orderId, valid: false }
      };
    }

    return {
      outcome: "success",
      output: { orderId: input.orderId, valid: true }
    };
  }
});

const result = await runStep(ValidateOrder, {
  orderId: "ord-1",
  itemsCount: 2
});

console.log(result.outcome);

Installation

Install only what you need.

Core

pnpm add @flowspine/core@beta

Extractor

pnpm add @flowspine/extractor@beta

CLI

pnpm add -D @flowspine/cli@beta

Viewer (optional)

pnpm add @flowspine/viewer@beta

CLI Quick Start

pnpm exec flowspine build --glob "processes/**/*.ts" --out ".flowspine/catalog.json"
pnpm exec flowspine validate --input ".flowspine/catalog.json"
pnpm exec flowspine export --input ".flowspine/catalog.json" --format mermaid --out ".flowspine/catalog.mmd"

Skills

Flowspine also has a dedicated skills repository for agent-oriented usage, repository-aware task execution, and package selection guidance.

Skills repository:

https://github.com/noarax/flowspine-skills

This is useful when you want an agent to understand:

• which package to use
• how to route a task correctly
• how to avoid inventing unsupported Flowspine behavior
• how to work safely with process graphs and step contracts

When To Use Which Package

Use @flowspine/core when:

• flow meaning changes
• step contracts change
• business logic changes
• step execution behavior matters

Use @flowspine/extractor when:

• code must be analyzed programmatically
• you are building custom tooling
• you need direct extraction control

Use @flowspine/cli when:

• validating the repo
• building catalog output
• exporting diagrams
• wiring CI or dev workflows

Important Constraints

• Flowspine does not auto-execute process graphs
• defineProcess(...) describes structure only
• defineStep(...) defines a step contract and handler
• runStep(...) executes one step only
• extractor works best with canonical DSL patterns
• CLI is an operational layer, not a runtime engine

Package Readmes

For package-specific details, see:

• packages/core/README.md
• packages/extractor/README.md
• packages/cli/README.md
• packages/viewer/README.md

License

Apache 2.0

Copyright

Copyright (c) 2026 Flowspine contributors.