Process Intelligence for People and Agents.
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.
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.
- Instrument your application: SDK quickstart.
- Investigate with an agent: MCP connection guide.
- Work with colleagues: project access and saved/shared investigations.
- Manage your account or data: sessions, exports and deletion.
- Build a custom consumer: public reads and portable evidence.
- Contribute: local setup and contribution guide.
Requires Node.js 20.19 or newer.
npm i @flowmarkdev/nodeCreate 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.
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.
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.
- flowmark.dev — product
- app.flowmark.dev — dashboard
- docs.flowmark.dev — guides and SDK reference
- api.flowmark.dev — API
@flowmarkdev/node— npmpackages/sdk/README.md— package details
| 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.
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 devpnpm 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.
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.