flowmark.

Understand what your software actually does.

Flowmark is an open-source process-intelligence platform for people and AI agents. Instrument the processes your application already runs, collect execution evidence, and understand technical and reported business outcomes over time.

Today, the TypeScript SDK and web interface support workflow investigation, related executions, progress, outcomes, confirmations and historical business analytics. Your application keeps ownership of execution.

Product 1.0 direction: Flowmark Platform supplies the programmable foundation, Flowmark Studio is the investigation workspace, and Flowmark Everywhere is the direction for agents, custom tools and portable interfaces. These are dimensions of one product. Studio is the current dashboard. The API serves six read-only MCP investigation tools when that deployment enables agent access. Saved investigations and a portable agent UI are not built.

Getting started

Requires Node.js 20.19 or newer.

npm i @flowmarkdev/node

Create one shared client. Keep the write key on the server. Never place it in NEXT_PUBLIC_* or a browser bundle. FLOWMARK_API_URL is the API origin, not a path such as /v1/events.

FLOWMARK_API_KEY=<project write key>
FLOWMARK_API_URL=https://api.flowmark.dev

// Next.js Route Handler or Server Action
import { createFlowmark } from "@flowmarkdev/node/next"

export const flowmark = createFlowmark()

// Node.js worker or long-lived server
import { createFlowmark } from "@flowmarkdev/node"

export const flowmark = createFlowmark()

export async function completeCheckout(orderId: string) {
  const flow = flowmark.workflow("checkout.order", {
    properties: { orderId },
  })

  try {
    flow.step("payment-captured")
    const shipment = await flow.operation("create-shipment", () =>
      createShipment(orderId),
    )
    flow.done({
      outcome: "complete",
      result: { shipmentId: shipment.id },
    })
    return shipment
  } catch (error) {
    flow.fail({ code: "CHECKOUT_FAILED" })
    throw error
  }
}

The function keeps its return value and its thrown errors. In Node.js, call await flowmark.shutdown() before the process exits. The Next.js client drains delivery with after().

Create a project and a write key in the dashboard, run the code, and open the recorded execution. Browser setup, typed workflows, and the rest of the API are in the documentation.

Capabilities

Follow one execution. Open a run and see the sequence of milestones and operations, where time was spent, the latest progress, and the errors your code recorded along the way.

Read the reported result. done() and fail() can carry a business outcome and a small JSON summary: imported and skipped counts, a shipment id, how far a sync got. The same facts are available on the run and across recent history.

See what changed. Workflow views show volume, completion, duration, and reported outcomes over time. Compare a recent window, then open the runs behind the change.

Find a specific case. Search run history by an enabled business reference, such as an order or customer id, and continue from that run into the timeline.

Connect related work. Continue one run across later requests with the same workflow name and id. Pass correlationId or parentRunId when separate runs belong together.

How it works

Your application keeps running the work. Flowmark records the markers you add around it.

Your application
  -> @flowmarkdev/node
  -> https://api.flowmark.dev
  -> a project in the dashboard

A workflow is a stable name, such as checkout.order. A run is one execution of that name. Steps are milestones. Operations are timed pieces of work and may overlap. Progress is an absolute snapshot. An outcome is the business result your code chooses to report, alongside technical completion or failure.

The same markers work from a Node.js process, a Next.js server, or the browser. Browser clients use a public browser key, or a same-origin proxy that keeps the server write key private. See browser integration.

Self-hosting uses these applications, the committed migrations, and PostgreSQL you control.

Documentation

• flowmark.dev — product
• app.flowmark.dev — dashboard
• docs.flowmark.dev — guides and SDK reference
• api.flowmark.dev — API
• @flowmarkdev/node — npm
• packages/sdk/README.md — package details

Repository

Path	Role
packages/sdk	Public SDK, @flowmarkdev/node
packages/core	Shared event contracts, @flowmarkdev/core
packages/api	Use cases and ports
packages/db	Schema, migrations, and persistence
packages/auth	Sessions, local accounts, and agent access
packages/mcp	Private read-only MCP adapter
apps/server	HTTP, tRPC, and MCP route shell
apps/dashboard	Studio
apps/web	Landing page
apps/docs	Customer documentation

apps/dev-harness and apps/internal-docs are local-only and bind to loopback. The architecture guide describes how the pieces connect.

Local development

Node.js 20.19 or newer, pnpm 10.18.1, and Docker Compose.

pnpm install
pnpm dev:setup
pnpm infra up
pnpm db:setup
pnpm dev

pnpm db:setup runs once against this checkout's Compose database. Do not point it at a hosted database. The dashboard is at http://localhost:3001.

Ports, checks, Drizzle Studio, and database safety are in the development guide.

Contributing

See CONTRIBUTING.md and SECURITY.md. Feature branches start from staging and open pull requests into staging. Releases follow application releases. Maintained hosted infrastructure follows the Pulumi writer policy.

• Development
• Architecture
• Documentation index
• Decisions

License

MIT