scriptoriumadmin/fabro
1
0
Fork 0
mirror of https://github.com/fabro-sh/fabro.git synced 2026-10-03 02:24:33 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 4

Describe the Petri layering in AGENTS.md and the architecture doc

Browse source 
The crate list names what fabro-workflow still holds and adds
fabro-graphviz; the architecture page describes Petri as the engine
every run executes on, at create and in the worker, in place of the
deleted in-process engine.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
This commit is contained in:
Bryan Helmkamp 2026-09-18 11:32:06 -04:00
parent af38d68942
commit 753c926072
No known key found for this signature in database
2 changed files with 11 additions and 9 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

10
AGENTS.md
View file

@ -119,11 +119,12 @@ Before merging changes that add or move shared test helpers, verify:
## Architecture
Fabro is an AI-powered workflow orchestration platform. Workflows are defined as Graphviz graphs, where each node is a stage (agent, prompt, command, conditional, human, parallel, etc.) executed by the workflow engine.
Fabro is an AI-powered workflow orchestration platform. Workflows are defined as Graphviz graphs, where each node is a stage (agent, prompt, command, conditional, human, parallel, etc.). Petri, the workflow engine, admits a workflow at create and executes every run; `fabro-petri` is the only crate that imports it.
### Rust crates (`lib/apps/`, `lib/components/`, and `lib/foundation/`)
- **fabro-cli** — CLI entry point. Commands: `run`, `exec`, `serve`, `validate`, `parse`, `cp`, `model`, `doctor`, `install`, `ps`, `system prune`
- **fabro-workflow** — Core workflow engine. Parses Graphviz graphs, runs stages, manages checkpoints/resume, hooks, and human-in-the-loop interactions
- **fabro-workflow** — Fabro's workflow definitions: parses Graphviz graphs and layers settings for the read side, creates and archives runs, and holds the run tools and the pull request pipeline. Execution is Petri's, through `fabro-petri`
- **fabro-graphviz** — Graphviz DOT parser, the typed graph model, and SVG rendering
- **fabro-sandbox** — Local, Docker, and Daytona sandbox providers. `RunSandbox` is also the `Environment` pebble's coding agent runs its tools through; agent stages, Ask Fabro, hook evaluators, and `fabro exec` all run on the `pebble-coding-agent` crate (pinned by rev in the workspace `Cargo.toml`). `RunSandbox` is also the `Environment` pebble's coding agent runs its tools through; agent stages, Ask Fabro, hook evaluators, and `fabro exec` all run on the `pebble-coding-agent` crate (pinned by rev in the workspace `Cargo.toml`). Docker is the default runtime provider and creates clone-based `/workspace` containers through the operator's Docker daemon; Daytona uses the same GitHub-only clone-source contract. Docker daemon access is host-root-equivalent and assumes trusted callers/payloads.
- **fabro-petri** — Fabro's adapters over Petri, the workflow engine: the one crate that imports the Petri packages (pinned by rev in the workspace `Cargo.toml`), holding the run store over SQLite and the platform adapters
- **fabro-server** — Axum HTTP server. Routes for runs, sessions, models, completions, usage. SSE event streaming. Demo mode via header
@ -238,11 +239,12 @@ Before merging changes that add or move shared test helpers, verify:
## Architecture
Fabro is an AI-powered workflow orchestration platform. Workflows are defined as Graphviz graphs, where each node is a stage (agent, prompt, command, conditional, human, parallel, etc.) executed by the workflow engine.
Fabro is an AI-powered workflow orchestration platform. Workflows are defined as Graphviz graphs, where each node is a stage (agent, prompt, command, conditional, human, parallel, etc.). Petri, the workflow engine, admits a workflow at create and executes every run; `fabro-petri` is the only crate that imports it.
### Rust crates (`lib/apps/`, `lib/components/`, and `lib/foundation/`)
- **fabro-cli** — CLI entry point. Commands: `run`, `exec`, `serve`, `validate`, `parse`, `cp`, `model`, `doctor`, `install`, `ps`, `system prune`
- **fabro-workflow** — Core workflow engine. Parses Graphviz graphs, runs stages, manages checkpoints/resume, hooks, and human-in-the-loop interactions
- **fabro-workflow** — Fabro's workflow definitions: parses Graphviz graphs and layers settings for the read side, creates and archives runs, and holds the run tools and the pull request pipeline. Execution is Petri's, through `fabro-petri`
- **fabro-graphviz** — Graphviz DOT parser, the typed graph model, and SVG rendering
- **fabro-sandbox** — Local, Docker, and Daytona sandbox providers. `RunSandbox` is also the `Environment` pebble's coding agent runs its tools through; agent stages, Ask Fabro, hook evaluators, and `fabro exec` all run on the `pebble-coding-agent` crate (pinned by rev in the workspace `Cargo.toml`). `RunSandbox` is also the `Environment` pebble's coding agent runs its tools through; agent stages, Ask Fabro, hook evaluators, and `fabro exec` all run on the `pebble-coding-agent` crate (pinned by rev in the workspace `Cargo.toml`). Docker is the default runtime provider and creates clone-based `/workspace` containers through the operator's Docker daemon; Daytona uses the same GitHub-only clone-source contract. Docker daemon access is host-root-equivalent and assumes trusted callers/payloads.
- **fabro-petri** — Fabro's adapters over Petri, the workflow engine: the one crate that imports the Petri packages (pinned by rev in the workspace `Cargo.toml`), holding the run store over SQLite and the platform adapters
- **fabro-server** — Axum HTTP server. Routes for runs, sessions, models, completions, usage. SSE event streaming. Demo mode via header

10
docs/public/reference/architecture.mdx
View file

@ -3,11 +3,11 @@ title: "Architecture"
description: "How Fabro's CLI and API modes work under the hood"
---
Fabro provides two interfaces — a CLI for local development and an HTTP API for production use. Both share a common workflow engine.
Fabro provides two interfaces — a CLI for local development and an HTTP API for production use. Both submit runs to the same server, and every run executes on the same engine.
## Shared engine
## The engine
At the core of both modes is the `WorkflowRunEngine`. It parses the Graphviz graph, walks nodes, dispatches to handlers (agent, command, human, etc.), selects edges, and checkpoints after each stage. The engine is parameterized by an `Interviewer` trait that controls how human-in-the-loop questions are presented — terminal prompts in CLI mode, HTTP request/response in API mode.
Every run executes on Petri, the workflow engine. At create time the server hands Petri the workflow bundle and the run's settings; Petri lowers the Graphviz graph, checks it, pins the models its nodes name, and either admits the graph or refuses the run with its diagnostics. At execution a worker process runs the admitted graph: it walks the nodes, dispatches each stage (agent, command, human, etc.), selects edges, and records every step in the run's log, from which the run resumes after an interruption. Human-in-the-loop questions reach the server's questions API; the CLI answers them from the terminal, the web app from the run page.
## CLI mode
@ -15,7 +15,7 @@ At the core of both modes is the `WorkflowRunEngine`. It parses the Graphviz gra
fabro run workflow.fabro --goal "Implement the login feature"
```
The CLI parses the workflow, creates the engine with a `ConsoleInterviewer`, and executes synchronously. Events are printed to stderr, progress is shown with terminal indicators, and human-in-the-loop questions are answered via interactive terminal prompts. When the run finishes, the process exits.
The CLI builds the run manifest, submits it to the server (starting a local one when none is running), and follows the run: events are printed to stderr, progress is shown with terminal indicators, and human-in-the-loop questions are answered via interactive terminal prompts. When the run finishes, the process exits.
CLI mode is ideal for:
- Local development and iteration on workflows
@ -50,7 +50,7 @@ Key server config options:
2. **Start request** — `POST /api/v1/runs/{id}/start` moves normal runs to `runnable`. Parent-generated [child runs](/execution/child-runs) may move to `pending` with `approval_required`.
3. **Approve if needed** — `POST /api/v1/runs/{id}/approve` moves an approval-gated run to `runnable`; `deny` fails it with `approval_denied`.
4. **Schedule** — A background scheduler promotes `runnable` runs to `running` in FIFO order, up to the concurrency limit.
5. **Execute** — The engine walks the graph, streaming events to all subscribers.
5. **Execute** — A worker runs the admitted graph on Petri, streaming events to all subscribers.
6. **Complete** — The run transitions to `succeeded`, `failed`, or `dead`.
### Event streaming