Authoring surface
React Flow and Liveblocks make the canvas collaborative. Node data remains plain JSON so it can move between the browser, room storage, and database without a translation layer.
Back to ForgeFlow
ForgeFlow engineering learnings
A practical map of the architecture, maintenance boundaries, and debugging lessons behind ForgeFlow. This is intentionally specific to the codebase rather than a general workflow-automation guide.
Core mental model
ForgeFlow separates collaborative authoring from durable execution so each system can do one job well.
Execution contract
The database stores the validated graph snapshot. Trigger.dev reads that snapshot with the owning organization id instead of trusting a browser payload after the run begins.
One browser per run
Browser steps share one lazy Stagehand session. This preserves login state between nodes and produces one Browserbase recording for the run.
Where each responsibility lives
Most regressions are ownership mistakes. Before moving code or state, decide which system is authoritative and what it must never be trusted to do.
React Flow + Liveblocks
Owns: Canvas edits, node positions, edges, cursors, and presence
Must not own: The graph that a task executes or durable run history
components/canvas.tsx, components/room.tsxNext.js server
Owns: Authentication, entitlement checks, mutations, cache revalidation, and integration routes
Must not own: Long-running browser work or secret-bearing client state
features/workflows/actions.ts, app/api/Postgres + Drizzle
Owns: Organization-owned workflow identity and the executable JSONB graph snapshot
Must not own: Realtime cursor state or transient step progress
lib/db/schema.ts, features/workflows/data.tsTrigger.dev
Owns: Durable queued execution, retries, logs, cancellation, and realtime run metadata
Must not own: Clerk session authorization or a permanent ForgeFlow audit record
features/workflows/tasks/run-workflow.tsBrowserbase + Stagehand
Owns: A run-scoped browser, automation calls, recording, and replay source
Must not own: Authorization decisions or browser-visible API secrets
nodes/*.ts, lib/browserbase.ts, api/replays/Resend
Owns: Actual email delivery and duplicate-request rejection
Must not own: Workflow scheduling or retry policy
nodes/send-email.tsArchitecture and workflow lessons
These decisions keep the visual canvas, runner, and external services coherent as node types evolve.
Workflow engine
One registry is the node contract
The node registry defines kinds, fields, icons, and outputs, while the executor map satisfies every action-node type at compile time. Adding a node is a three-file change, not a canvas rewrite.
features/workflows/nodes/Persistence
The saved graph is what runs
Liveblocks holds the collaborative editing copy. The Run action validates and writes an organization-owned JSONB snapshot before Trigger.dev loads and executes it.
features/workflows/actions.ts and data.tsState management
Realtime state is not durable history
Trigger metadata powers live node status and output while a run is active. A future run-history view should use a durable record rather than assume a realtime subscription is a permanent audit log.
workflow-runs-provider.tsx and run-workflow.tsReliability
Side effects need a run identity
Workflow tasks retry. The Send Email executor receives the Trigger run id and node id so Resend can reject a duplicate attempt without blocking a deliberately new workflow run.
node-executors.ts and send-email.tsBrowser automation
The browser session belongs to the run
Stagehand opens lazily on the first browser node and is reused for later browser nodes. A finally block closes it whether the run succeeds, fails, or is cancelled.
features/workflows/tasks/run-workflow.tsAuthorization
Pro gates belong on the server too
The palette can guide users to upgrade, but direct Server Action calls remain possible. Agent execution and replay retrieval independently check the active organization plan on the server.
actions.ts and app/api/replays/[sessionId]/route.tsInput safety
Manifest requirements are not runtime validation
A node field can be marked required in the registry and highlighted in the editor, yet the current server validator checks only graph structure. Treat node values as untrusted executor input until field-level validation exists on both sides of the boundary.
node-registry.ts and lib/validate-graph.tsProduct policy
Billing configuration is not execution policy
Clerk Billing advertises several plan features, but ForgeFlow code currently enforces only the Pro plan for Agent execution and replay. A plan label or configured feature has no effect until a server boundary checks it.
billing.json, use-pro-gate.ts, actions.tsChange playbooks
Use these checklists when changing the system. They encode the hidden cross-file contracts that are easy to miss in an otherwise small feature.
Add a workflow node
- 1.Implement one executor under features/workflows/nodes/.
- 2.Register it in node-executors.ts so action coverage remains type checked.
- 3.Declare the node manifest, fields, outputs, and visual metadata in node-registry.ts.
- 4.Keep inputs and outputs JSON-safe, then add validation and documentation for its side effects.
Add a paid or sensitive capability
- 1.Use the client gate only to explain the experience.
- 2.Enforce the plan and organization on the server entry point.
- 3.Bind external identifiers to an owned workflow or run before using them.
- 4.Check that errors do not disclose other organizations or secret values.
Change the workflow data model
- 1.Update Drizzle schema types before consumers; never hand-write row shapes.
- 2.Generate and review a migration, then validate old and new graph snapshots.
- 3.Preserve orgId in every query and ensure the Trigger task can reload the new data.
- 4.Run a real worker execution, not only a browser save flow.
Change task or replay behavior
- 1.Read the current Trigger.dev or Browserbase documentation before changing SDK calls.
- 2.Preserve run tags, concise metadata, idempotency, and finally cleanup.
- 3.Treat asynchronous recording readiness as pending, not authorization failure.
- 4.Exercise another organization's access path to verify the negative case.
Debugging notes
Start from the durable system that owns the behavior, then work outward to the user interface.
A workflow appears to run but a node never updates
Inspect the Trigger run metadata first. The runner publishes pending, running, done, and failed steps; a missing step usually means the graph was not saved or the node is disconnected.
A replay keeps preparing
Browserbase records asynchronously after a session closes. The replay route translates the temporary not-ready state to HTTP 202, and the player polls it instead of treating it as a hard failure.
A value token resolves to an empty string
Verify the upstream node ran first and that the token path matches one of the outputs in the registry. Missing paths deliberately interpolate to an empty string so a template never crashes the runner.
An email node looks successful without a message id
Resend returns errors in its response object rather than throwing. Treat an error or missing data object as a failed step, then verify the Resend API key and sender domain.
A visually required node field is empty
The current graph validator deliberately checks only one Start node, at least one edge, and no cycle. Inspect the executor input and add explicit validation before relying on a red required marker as a safety boundary.
Telemetry is silent or unexpectedly expensive
Check SENTRY_DSN first, then review the current 1.0 trace sample rate and browser Replay sampling. The sample Sentry page and API are probes; they are not evidence that ordinary product errors are correctly classified.
Performance and deployment
The useful optimization is usually a clear ownership boundary, not a clever cache.
Keep metadata small
Run metadata is realtime UI state with a finite size budget. Publish step summaries and serializable outputs, not browser objects or full page payloads.
Deploy every secret to the right runtime
Browserbase, Liveblocks, Resend, Trigger.dev, and database credentials stay server-side. Only Clerk's publishable key is meant for the browser.
Validate before release
Run typecheck, lint, build, database migrations, and a real organization-scoped browser run. Replay verification is part of the security check, not only a UI test.
Invariants for future changes
These are small rules with large consequences. Keep them true when adding nodes, changing tasks, or evolving the collaboration model.
Every workflow read, update, and delete includes the active organization id.
Only connected nodes execute; a graph must contain one Start trigger and no cycle.
A browser session is created lazily and always closed by the task runner.
Replay access verifies the user, organization, Pro plan, workflow ownership, run tag, and session id.
Action-node executor coverage stays compile-time checked against the registry.
Liveblocks room permissions and identity group ids use the same Clerk organization id.
Deliberate limits and future decisions
These are current product boundaries, not accidental omissions. Preserve them or replace them with an explicit design and migration plan.
- Workflow edits become the executable database snapshot when Run saves a validated graph; there is no separate explicit Save command yet.
- Trigger metadata is live progress, not a durable ForgeFlow run-history data model.
- Email content is sent as text; do not silently change its semantics to HTML without a product decision and sanitization design.
- The replay player selects the first Browserbase page only; multi-page recordings need a deliberate page-selection design.
- Workflow deletion can leave a Liveblocks room behind because room cleanup is best-effort after the database row has been removed.
- The public /test route is a design-system sandbox, and the Sentry example routes are integration probes. Neither represents a customer workflow capability.
- There is no application-level rate limiting and no schema index beyond the workflow primary key; measure and design those controls before claiming high-scale behavior.
- The application has no automated test suite yet. Typecheck, lint, production build, and a real organization-scoped run are the current release floor.
- Transitive dependency advisories remain upstream. Do not use npm audit fix --force without an approved compatibility plan and a full rebuild.
Mistakes to avoid next
- Do not add a node in only the palette: registry and executor coverage are both required.
- Do not make a client-side billing gate the only protection for an expensive capability.
- Do not proxy a Browserbase replay by session id alone; bind it to the authenticated workflow run.
- Do not let a failed or cancelled task skip Browserbase cleanup.
- Do not treat Liveblocks presence as durable workflow state.
The most useful next improvements are durable run history, explicit save semantics, automated authorization coverage, and richer graph-level validation.
Open ForgeFlow