# joshuaisaact/petri-flow architecture

> Architecture diagram of the GitHub repository joshuaisaact/petri-flow, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-07). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/joshuaisaact/petri-flow
- Repository: https://github.com/joshuaisaact/petri-flow

## Overview

PetriFlow has two product tracks: declarative policies compiled into Petri-net tool gates for agent frameworks, and a general workflow runtime with analysis, persistence, CLI, and an interactive viewer/editor. The safety path runs from policy compilation through composed gate decisions and framework adapters. The workflow path defines nets, analyzes and executes them, then exposes them through CLI and viewer tooling. Relationships below rely on README capability statements and SOURCE INDEX references; unsampled implementation details are not asserted.

Main entry points: [`packages/gate/src/manager.ts`](https://github.com/joshuaisaact/petri-flow/blob/main/packages/gate/src/manager.ts) (Gate manager), [`apps/viewer/src/App.tsx`](https://github.com/joshuaisaact/petri-flow/blob/main/apps/viewer/src/App.tsx) (Viewer and editor), [`packages/engine/src/scheduler.ts`](https://github.com/joshuaisaact/petri-flow/blob/main/packages/engine/src/scheduler.ts) (Scheduler), [`packages/engine/src/engine.ts`](https://github.com/joshuaisaact/petri-flow/blob/main/packages/engine/src/engine.ts) (Firing engine)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_policy["Safety policies"]
  node_rules["Rules compiler<br/>[compiler.ts]"]
end

subgraph group_gating["Tool gating"]
  node_gate["Gate manager<br/>[manager.ts]"]
  node_gatecompose["Net composition<br/>[compose.ts]"]
  node_gateadvance["Deferred advance<br/>[advance.ts]"]
  node_gateevents["Tool events<br/>[events.ts]"]
end

subgraph group_adapters["Agent adapters"]
  node_vercel["Vercel AI adapter<br/>[index.ts]"]
  node_pi["Pi adapter<br/>[index.ts]"]
  node_agent_sdk["Agent SDK adapter<br/>[index.ts]"]
  node_claude["Claude Code hook<br/>[hook.ts]"]
  node_openclaw["OpenClaw adapter<br/>[index.ts]"]
  node_skill_nets["Reusable skill nets<br/>[research.ts]"]
end

subgraph group_runtime["Workflow runtime"]
  node_workflow_defs["Workflow definitions"]
  node_engine["Firing engine<br/>[engine.ts]"]
  node_analysis["Workflow analysis<br/>[analyse.ts]"]
  node_executor["Workflow executor<br/>[executor.ts]"]
  node_scheduler["Scheduler<br/>[scheduler.ts]"]
  node_persistence[("Persistence adapters<br/>[sqlite-adapter.ts]")]
  node_cli["Analysis CLI<br/>[cli.ts]"]
  node_benchmark["Agent benchmark<br/>[definition.ts]"]
  node_comparison["Safety scenarios"]
end

subgraph group_viewer["Workflow viewer"]
  node_viewer_app["Viewer and editor<br/>[App.tsx]"]
  node_viewer_state["Simulation state<br/>[usePetriNet.ts]"]
  node_viewer_analysis["Live analysis<br/>[useAnalysis.ts]"]
  node_canvas["Net canvas<br/>[PetriNetCanvas.tsx]"]
  node_editor_state["Editor state<br/>[useEditorState.ts]"]
  node_layout["Graph layout<br/>[dagre.ts]"]
  node_definitions_api["Definition API"]
end

node_agent(("Agent tools"))

node_agent -->|"calls tools"| node_vercel
node_rules -->|"compiles policies"| node_gate
node_vercel -->|"wraps tools"| node_gate
node_pi -->|"intercepts calls"| node_gate
node_agent_sdk -->|"uses callbacks"| node_gate
node_claude -->|"gates hooks"| node_gate
node_openclaw -->|"maps hooks"| node_gate
node_skill_nets -->|"provides nets"| node_gate
node_gate -->|"dispatches calls"| node_gatecompose
node_gate -->|"advances state"| node_gateadvance
node_gate -->|"handles events"| node_gateevents
node_workflow_defs -->|"defines nets"| node_engine
node_engine -->|"fires transitions"| node_executor
node_workflow_defs -->|"proves properties"| node_analysis
node_scheduler -->|"ticks workflows"| node_executor
node_scheduler -->|"persists state"| node_persistence
node_cli -->|"runs analysis"| node_analysis
node_benchmark -->|"runs workflow"| node_scheduler
node_comparison -->|"defines scenarios"| node_engine
node_viewer_app -->|"hosts simulation"| node_viewer_state
node_viewer_app -->|"shows analysis"| node_viewer_analysis
node_viewer_app -->|"renders net"| node_canvas
node_viewer_app -->|"hosts editing"| node_editor_state
node_editor_state -->|"requests layout"| node_layout
node_viewer_app -->|"loads definitions"| node_definitions_api

click node_rules "https://github.com/joshuaisaact/petri-flow/blob/main/packages/rules/src/compiler.ts"
click node_gate "https://github.com/joshuaisaact/petri-flow/blob/main/packages/gate/src/manager.ts"
click node_gatecompose "https://github.com/joshuaisaact/petri-flow/blob/main/packages/gate/src/compose.ts"
click node_gateadvance "https://github.com/joshuaisaact/petri-flow/blob/main/packages/gate/src/advance.ts"
click node_gateevents "https://github.com/joshuaisaact/petri-flow/blob/main/packages/gate/src/events.ts"
click node_vercel "https://github.com/joshuaisaact/petri-flow/blob/main/packages/vercel-ai/src/index.ts"
click node_pi "https://github.com/joshuaisaact/petri-flow/blob/main/packages/pi-extension/src/index.ts"
click node_agent_sdk "https://github.com/joshuaisaact/petri-flow/blob/main/packages/agent-sdk/src/index.ts"
click node_claude "https://github.com/joshuaisaact/petri-flow/blob/main/packages/claude-code/src/hook.ts"
click node_openclaw "https://github.com/joshuaisaact/petri-flow/blob/main/packages/openclaw/src/index.ts"
click node_skill_nets "https://github.com/joshuaisaact/petri-flow/blob/main/packages/pi-assistant/src/nets/research.ts"
click node_workflow_defs "https://github.com/joshuaisaact/petri-flow/tree/main/workflows"
click node_engine "https://github.com/joshuaisaact/petri-flow/blob/main/packages/engine/src/engine.ts"
click node_analysis "https://github.com/joshuaisaact/petri-flow/blob/main/packages/engine/src/analyse.ts"
click node_executor "https://github.com/joshuaisaact/petri-flow/blob/main/packages/engine/src/executor.ts"
click node_scheduler "https://github.com/joshuaisaact/petri-flow/blob/main/packages/engine/src/scheduler.ts"
click node_persistence "https://github.com/joshuaisaact/petri-flow/blob/main/packages/engine/src/persistence/sqlite-adapter.ts"
click node_cli "https://github.com/joshuaisaact/petri-flow/blob/main/packages/cli/src/cli.ts"
click node_benchmark "https://github.com/joshuaisaact/petri-flow/blob/main/workflows/agent-benchmark/definition.ts"
click node_comparison "https://github.com/joshuaisaact/petri-flow/blob/main/comparisons/openclaw-safety/src/scenarios/sandbox-isolation.ts"
click node_viewer_app "https://github.com/joshuaisaact/petri-flow/blob/main/apps/viewer/src/App.tsx"
click node_viewer_state "https://github.com/joshuaisaact/petri-flow/blob/main/apps/viewer/src/hooks/usePetriNet.ts"
click node_viewer_analysis "https://github.com/joshuaisaact/petri-flow/blob/main/apps/viewer/src/hooks/useAnalysis.ts"
click node_canvas "https://github.com/joshuaisaact/petri-flow/blob/main/apps/viewer/src/components/canvas/PetriNetCanvas.tsx"
click node_editor_state "https://github.com/joshuaisaact/petri-flow/blob/main/apps/viewer/src/editor/useEditorState.ts"
click node_layout "https://github.com/joshuaisaact/petri-flow/blob/main/apps/viewer/src/layout/dagre.ts"
click node_definitions_api "https://github.com/joshuaisaact/petri-flow/blob/main/apps/viewer/src/editor/useDefinitionsApi.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_rules toneBlue
class node_gate,node_gatecompose,node_gateadvance,node_gateevents toneAmber
class node_vercel,node_pi,node_agent_sdk,node_claude,node_openclaw,node_skill_nets toneMint
class node_workflow_defs,node_engine,node_analysis,node_executor,node_scheduler,node_persistence,node_cli,node_benchmark,node_comparison toneRose
class node_viewer_app,node_viewer_state,node_viewer_analysis,node_canvas,node_editor_state,node_layout,node_definitions_api,node_agent toneIndigo
```

## Components

### Safety policies

- [Rules compiler](https://github.com/joshuaisaact/petri-flow/blob/main/packages/rules/src/compiler.ts): `packages/rules/src/compiler.ts`

### Tool gating

- [Gate manager](https://github.com/joshuaisaact/petri-flow/blob/main/packages/gate/src/manager.ts): `packages/gate/src/manager.ts`
- [Net composition](https://github.com/joshuaisaact/petri-flow/blob/main/packages/gate/src/compose.ts): `packages/gate/src/compose.ts`
- [Deferred advance](https://github.com/joshuaisaact/petri-flow/blob/main/packages/gate/src/advance.ts): `packages/gate/src/advance.ts`
- [Tool events](https://github.com/joshuaisaact/petri-flow/blob/main/packages/gate/src/events.ts): `packages/gate/src/events.ts`

### Agent adapters

- [Vercel AI adapter](https://github.com/joshuaisaact/petri-flow/blob/main/packages/vercel-ai/src/index.ts): `packages/vercel-ai/src/index.ts`
- [Pi adapter](https://github.com/joshuaisaact/petri-flow/blob/main/packages/pi-extension/src/index.ts): `packages/pi-extension/src/index.ts`
- [Agent SDK adapter](https://github.com/joshuaisaact/petri-flow/blob/main/packages/agent-sdk/src/index.ts): `packages/agent-sdk/src/index.ts`
- [Claude Code hook](https://github.com/joshuaisaact/petri-flow/blob/main/packages/claude-code/src/hook.ts): `packages/claude-code/src/hook.ts`
- [OpenClaw adapter](https://github.com/joshuaisaact/petri-flow/blob/main/packages/openclaw/src/index.ts): `packages/openclaw/src/index.ts`
- [Reusable skill nets](https://github.com/joshuaisaact/petri-flow/blob/main/packages/pi-assistant/src/nets/research.ts): `packages/pi-assistant/src/nets/research.ts`

### Workflow runtime

- [Workflow definitions](https://github.com/joshuaisaact/petri-flow/tree/main/workflows): `workflows`
- [Firing engine](https://github.com/joshuaisaact/petri-flow/blob/main/packages/engine/src/engine.ts): `packages/engine/src/engine.ts`
- [Workflow analysis](https://github.com/joshuaisaact/petri-flow/blob/main/packages/engine/src/analyse.ts): `packages/engine/src/analyse.ts`
- [Workflow executor](https://github.com/joshuaisaact/petri-flow/blob/main/packages/engine/src/executor.ts): `packages/engine/src/executor.ts`
- [Scheduler](https://github.com/joshuaisaact/petri-flow/blob/main/packages/engine/src/scheduler.ts): `packages/engine/src/scheduler.ts`
- [Persistence adapters](https://github.com/joshuaisaact/petri-flow/blob/main/packages/engine/src/persistence/sqlite-adapter.ts): `packages/engine/src/persistence/sqlite-adapter.ts`
- [Analysis CLI](https://github.com/joshuaisaact/petri-flow/blob/main/packages/cli/src/cli.ts): `packages/cli/src/cli.ts`
- [Agent benchmark](https://github.com/joshuaisaact/petri-flow/blob/main/workflows/agent-benchmark/definition.ts): `workflows/agent-benchmark/definition.ts`
- [Safety scenarios](https://github.com/joshuaisaact/petri-flow/blob/main/comparisons/openclaw-safety/src/scenarios/sandbox-isolation.ts): `comparisons/openclaw-safety/src/scenarios/sandbox-isolation.ts`

### Workflow viewer

- [Viewer and editor](https://github.com/joshuaisaact/petri-flow/blob/main/apps/viewer/src/App.tsx): `apps/viewer/src/App.tsx`
- [Simulation state](https://github.com/joshuaisaact/petri-flow/blob/main/apps/viewer/src/hooks/usePetriNet.ts): `apps/viewer/src/hooks/usePetriNet.ts`
- [Live analysis](https://github.com/joshuaisaact/petri-flow/blob/main/apps/viewer/src/hooks/useAnalysis.ts): `apps/viewer/src/hooks/useAnalysis.ts`
- [Net canvas](https://github.com/joshuaisaact/petri-flow/blob/main/apps/viewer/src/components/canvas/PetriNetCanvas.tsx): `apps/viewer/src/components/canvas/PetriNetCanvas.tsx`
- [Editor state](https://github.com/joshuaisaact/petri-flow/blob/main/apps/viewer/src/editor/useEditorState.ts): `apps/viewer/src/editor/useEditorState.ts`
- [Graph layout](https://github.com/joshuaisaact/petri-flow/blob/main/apps/viewer/src/layout/dagre.ts): `apps/viewer/src/layout/dagre.ts`
- [Definition API](https://github.com/joshuaisaact/petri-flow/blob/main/apps/viewer/src/editor/useDefinitionsApi.ts): `apps/viewer/src/editor/useDefinitionsApi.ts`

### Other components

- **Agent tools**

## Connections

- Agent tools → Vercel AI adapter: calls tools
- Rules compiler → Gate manager: compiles policies
- Vercel AI adapter → Gate manager: wraps tools
- Pi adapter → Gate manager: intercepts calls
- Agent SDK adapter → Gate manager: uses callbacks
- Claude Code hook → Gate manager: gates hooks
- OpenClaw adapter → Gate manager: maps hooks
- Reusable skill nets → Gate manager: provides nets
- Gate manager → Net composition: dispatches calls (evidence: `packages/gate/src/manager.ts`)
- Gate manager → Deferred advance: advances state (evidence: `packages/gate/src/manager.ts`)
- Gate manager → Tool events: handles events (evidence: `packages/gate/src/manager.ts`)
- Workflow definitions → Firing engine: defines nets
- Firing engine → Workflow executor: fires transitions
- Workflow definitions → Workflow analysis: proves properties
- Scheduler → Workflow executor: ticks workflows
- Scheduler → Persistence adapters: persists state
- Analysis CLI → Workflow analysis: runs analysis
- Agent benchmark → Scheduler: runs workflow
- Safety scenarios → Firing engine: defines scenarios
- Viewer and editor → Simulation state: hosts simulation
- Viewer and editor → Live analysis: shows analysis
- Viewer and editor → Net canvas: renders net
- Viewer and editor → Editor state: hosts editing
- Editor state → Graph layout: requests layout (evidence: `apps/viewer/src/editor/useEditorState.ts`)
- Viewer and editor → Definition API: loads definitions
