Skip to content
Mumma6Public

About

Workflow observability for TypeScript apps. Instrument existing processes and inspect every run with milestones, operations, context, errors, progress, and reported results.

Topics

Resources

Contributing

Security policy

Stars

1 star

Watchers

0 watching

Forks

Latest commit

 

History

511 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

Flowmark

flowmark.

Process Intelligence for People and Agents.
Understand what your software actually does.

npm MIT License flowmark.dev

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.

Platform supplies the programmable foundation, Studio is the investigation workspace, and Everywhere brings authorized evidence into agents, custom tools and portable interfaces. These are dimensions of one product.

Product 1.0 is implementation-complete in this repository. Studio includes reference journeys, linked comparisons, private and shared investigations, business-reader projections, account controls and data exports. The API provides public read endpoints and six read-only MCP tools when the deployment enables agent access. See implementation status for source boundaries and deliberate limitations.

Implementation completion is not a blanket deployment or compatibility claim. Vendor-client support, hosted capture/cleanup activation and operational acceptance remain separately recorded. Product 2.0 will build on this foundation with process health, easier discovery/capture and maintained process meaning; those are future capabilities, not promises about today's deployment.

Choose your path

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.

The repository supports local development and inspectable contributions. A supported self-host distribution is not a project goal; configurable origins are compatibility boundaries, not a promise of deployment support.

Documentation

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
packages/engine Effect adapter for the Rust Engine
crates/flowmark-engine Deterministic Rust computation
packages/evidence-view Portable supplied-data evidence views
packages/email Private transactional delivery
packages/ui Shared presentation and controls
packages/demo Synthetic local showcase tooling
packages/config Shared tool configuration
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

TypeScript + Effect is the primary application platform. PostgreSQL owns data-local persistence and analytics. Rust is a permanent architectural option for cohesive computation, analysis, algorithms and data processing; the Flowmark Engine is its first production integration. Future Rust modules and crates can build on the same explicit ownership and contract boundaries. See architecture.

Node.js 24.x (see .node-version), pnpm 10.18.1, and Docker Compose.

pnpm install
pnpm dev:setup
pnpm infra doctor
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.

License

MIT

About

Workflow observability for TypeScript apps. Instrument existing processes and inspect every run with milestones, operations, context, errors, progress, and reported results.

Topics

Resources

Contributing

Security policy

Stars

1 star

Watchers

0 watching

Forks

Releases

Used by

Contributors

Languages