Real-time collaborative canvas that humans and AI agents edit together. People work in the browser; agents connect through an MCP server, a CLI, or HTTP, and every change goes through the same typed, server-owned canvas commands. Built on React Flow, Yjs, and Hocuspocus.
- Real-time Collaboration - Multiple users can edit the same canvas simultaneously
- Conflict-free Sync - Powered by Yjs CRDT for seamless concurrent editing
- User Presence - See other users' cursors and selections in real-time, and watch agents move their own cursor as they edit
- Scoped Undo/Redo - Each user has independent undo history
- Node Types - Text, image, and video nodes
- Agent Access - Typed server-owned commands over HTTP, a local CLI, and an MCP endpoint
- Horizontal Scaling - Each canvas lives on one owner instance behind a database lease, with fenced writes; Redis Pub/Sub is available as an alternative mode
- Light and Dark Themes - Follows the system color scheme, canvas controls included
| Layer | Technology |
|---|---|
| Node Editor | React Flow |
| Real-time Sync | Yjs + Hocuspocus |
| Frontend | Next.js 16 + React 19 |
| Backend | Elysia on Bun |
| Database | PostgreSQL (node-postgres) + Drizzle ORM |
| UI Components | shadcn/ui on Base UI |
| Styling | Tailwind CSS v4 |
| Build System | Turborepo, bun build for the backend, tsdown for the CLI |
| Package Manager | pnpm |
- Node.js >= 26 (see
.node-version) for the web app and CLI - Bun 1.4+ (see
.bun-version) for the backend - pnpm 12 (pinned in
packageManager; Corepack or a recent pnpm picks it up) - PostgreSQL 16+ (
docker compose up -dstarts one with the default credentials)
# Clone the repository
git clone https://github.com/SweetRetry/flowpocus.git
cd flowpocus
# Install dependencies (also installs the Lefthook git hooks)
pnpm install
# Start PostgreSQL and apply the migrations
docker compose up -d
pnpm db:migrateAfter changing packages/database/src/schema, run pnpm db:generate to write a new migration, then pnpm db:migrate.
# Start all services (frontend + backend)
pnpm dev
# Or start individually
pnpm dev:web # Frontend at http://localhost:3000
pnpm dev:backend # Backend at http://localhost:3001Open http://localhost:3000/canvas (redirects to the showcase canvas) or
http://localhost:3000/canvas/{any-id}. A canvas is created on first connect.
# NEXT_PUBLIC_WS_URL is inlined at build time
NEXT_PUBLIC_WS_URL=wss://your-host/collaboration pnpm build
pnpm --filter @workspace/backend start # bun dist/index.js
pnpm --filter web start # next startEvery instance can accept any canvas. By default (CLUSTER_MODE=owner) a canvas loads on exactly one
instance, which holds a lease in PostgreSQL; the others forward its WebSocket and command traffic to that
owner. Give each instance a unique INSTANCE_ID and an INSTANCE_URL its peers can reach:
PORT=3001 INSTANCE_ID=a INSTANCE_URL=http://10.0.0.5:3001 pnpm --filter @workspace/backend start
PORT=3001 INSTANCE_ID=b INSTANCE_URL=http://10.0.0.6:3001 pnpm --filter @workspace/backend startSet CLUSTER_MODE=redis with REDIS_URL on every instance to sync copies over Redis instead. All instances
in a cluster must use the same mode. ADR 0001 explains the
trade-off and when to switch.
| Variable | Used by | Default |
|---|---|---|
PORT |
backend | 3001 |
DATABASE_URL |
backend, db:* scripts, tests |
postgres://flowpocus:flowpocus@localhost:5432/flowpocus |
CLUSTER_MODE |
backend, owner or redis (see docs/adr/0001-single-owner-placement.md) |
owner |
REDIS_URL |
backend, required when CLUSTER_MODE=redis |
unset |
INSTANCE_ID |
backend, lease owner and Redis node identity | random UUID |
INSTANCE_URL |
backend, address other instances forward to | http://localhost:$PORT |
LOG_LEVEL |
backend (debug, info, warn, error) |
info |
NEXT_PUBLIC_WS_URL |
web, at build time | ws://localhost:3001/collaboration |
FLOWPOCUS_SERVER_URL |
CLI | http://localhost:3001 |
Canvas Command contracts live in packages/commands; execution lives only in the backend.
The CLI and the MCP endpoint are transports for the same server commands.
# Create a target canvas
pnpm dev:cli canvases create --name "Agent Canvas"
# Discover commands and their JSON Schema from the server
pnpm dev:cli commands list
# Create a node; retry with the same command ID if the outcome is unknown
pnpm dev:cli commands execute create_node \
--canvas-id <canvasId> \
--command-id <stable-command-id> \
--input '{"type":"text","position":{"x":120,"y":80},"content":"Agent note"}'The backend serves a stateless Streamable HTTP MCP endpoint at /mcp with list_canvases,
get_canvas, and one tool per canvas command:
claude mcp add --transport http flowpocus http://localhost:3001/mcpflowpocus/
├── apps/
│ ├── web/ # Next.js frontend
│ ├── backend/ # Elysia on Bun + Hocuspocus + server-owned commands + MCP
│ └── cli/ # Agent-facing server API client
├── packages/
│ ├── commands/ # Shared Zod command contracts
│ ├── canvas/ # React Flow nodes, plugins & hooks
│ ├── ui/ # shadcn/ui components and theme tokens
│ ├── database/ # Drizzle ORM + PostgreSQL
│ └── typescript-config/ # Shared TypeScript configs
├── docs/ # Design notes
└── ...
| Command | Description |
|---|---|
pnpm dev |
Start development servers |
pnpm build |
Build all packages |
pnpm test |
Run tests |
pnpm typecheck |
Run TypeScript type checking |
pnpm lint |
Run Biome checks |
pnpm check |
Run Biome with auto-fix |
pnpm knip |
Find unused files, exports, and dependencies |
pnpm dev:cli <args> |
Call server-owned commands from the local CLI |
pnpm db:generate |
Write a migration from schema changes |
pnpm db:migrate |
Apply pending migrations |
pnpm db:studio |
Open Drizzle Studio |
- docs/ARCHITECTURE.md covers the data flow, sync, undo, and persistence in detail (Chinese).
- docs/adr records architecture decisions, starting with single-owner placement.
- docs/future holds open design questions, such as where to store Yjs snapshots.
Contributions are welcome! See CONTRIBUTING.md for setup, commit conventions, and the checks CI runs.
- Fork the repository
- Create your feature branch (
git checkout -b feature/amazing-feature) - Commit your changes (
git commit -m "feat: add amazing feature") - Push to the branch (
git push origin feature/amazing-feature) - Open a Pull Request
MIT License - see LICENSE for details.