FlowCreate

Distributed CRDT-backed finite state machines for backend APIs

FlowCreate is a production-ready TypeScript library that combines finite state machines (FSM) with CRDT-based conflict resolution to enable distributed stateful workflows in backend APIs.

Why FlowCreate?

Building stateful workflows in distributed systems is hard. FlowCreate solves this by:

• Deterministic State Management - FSM ensures valid state transitions
• Conflict-Free Replication - CRDT guarantees eventual consistency across nodes
• Zero Configuration - Works out of the box with sensible defaults
• Framework Agnostic - Use with Express, Fastify, or standalone

Perfect for order processing, approval workflows, ticket systems, and any stateful backend logic.

Features

• 🎯 Type-Safe FSM Engine - Define state machines with full TypeScript support
• 🔄 CRDT Conflict Resolution - Automatic last-write-wins resolution for distributed systems
• 🔌 Pluggable Storage - In-memory and database adapters (Supabase included)
• 🚀 HTTP Middleware - Express and Fastify middleware out of the box
• 📦 Monorepo Structure - Core library and CLI scaffolding tool
• ✅ Comprehensive Testing - Unit tests and property-based tests

Quick Start

Create a new FlowCreate app

npx @flowcreate/create-flowcreate-app my-app
cd my-app
npm install
npm run dev

Install the core library

npm install @flowcreate/core

Packages

This monorepo contains:

• @flowcreate/core - Core library with FSM, CRDT, and middleware
• @flowcreate/create-flowcreate-app - CLI scaffolding tool

Development

This project uses PNPM workspaces for monorepo management.

Prerequisites

• Node.js >= 18.0.0
• PNPM >= 8.0.0

Setup

# Install dependencies
pnpm install

# Build all packages
pnpm build

# Run tests
pnpm test

# Development mode (watch)
pnpm dev

Project Structure

flowcreate/
├── packages/
│   ├── core/                    # Core library
│   └── create-flowcreate-app/   # CLI tool
├── pnpm-workspace.yaml          # PNPM workspace config
├── package.json                 # Root package.json
└── tsconfig.json                # Shared TypeScript config

Example Usage

import express from 'express';
import { createExpressMiddleware, InMemoryStorage } from '@flowcreate/core';

const app = express();
app.use(express.json());

// Define your state machine
const orderFlow = {
  initial: 'pending',
  states: {
    pending: { events: { pay: 'paid' } },
    paid: { events: { ship: 'shipped' } },
    shipped: { events: { deliver: 'delivered' } },
    delivered: { events: {} }
  }
};

// Create middleware
app.use('/flows', createExpressMiddleware({
  flows: { orders: orderFlow },
  storage: new InMemoryStorage()
}));

app.listen(3000);

Then use the API:

# Apply a transition
curl -X POST http://localhost:3000/flows/orders/order-123/events/pay \
  -H "Content-Type: application/json" \
  -d '{"actorId":"user-1"}'

# Get current state
curl http://localhost:3000/flows/orders/order-123/state

Use Cases

• Order Management - Track orders through pending → paid → shipped → delivered
• Approval Workflows - Handle multi-step approval processes
• Ticket Systems - Manage support tickets with state transitions
• Content Moderation - Track content through review stages
• Booking Systems - Handle reservations and cancellations

Documentation

📚 Full Documentation - Complete guides, API reference, and examples

• Core Library Documentation
• CLI Tool Documentation
• Contributing Guide
• Changelog

Contributing

Contributions are welcome! Please read our Contributing Guide for details on our code of conduct and the process for submitting pull requests.

License

MIT © FlowCreate Contributors