mirror of
https://github.com/fabro-sh/fabro.git
synced 2026-08-28 05:27:41 +00:00
8726065fd1
Move the built web bundle into an embedded fabro-spa crate so Cargo and release builds no longer depend on Bun at build time, and preserve the local dev override path for fast UI iteration. At the same time, rename interview and agent-level aborted flows to interrupted, keep cancelled for run-level shutdown, and stop reporting skipped answers as interruptions in the run event stream.
92 lines
4.6 KiB
Text
92 lines
4.6 KiB
Text
---
|
|
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.
|
|
|
|
## Shared 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.
|
|
|
|
## CLI mode
|
|
|
|
```bash
|
|
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.
|
|
|
|
CLI mode is ideal for:
|
|
- Local development and iteration on workflows
|
|
- One-off runs and debugging
|
|
- Scripting and CI/CD pipelines
|
|
|
|
## API mode
|
|
|
|
```bash
|
|
fabro server start
|
|
```
|
|
|
|
`fabro server start` starts an HTTP server (default `127.0.0.1:3000`) with persistent run storage. Runs are submitted via the REST API and executed asynchronously.
|
|
|
|
### Configuration
|
|
|
|
The server reads `~/.fabro/settings.toml` for default settings (model, sandbox, variables, authentication). This file is live-reloaded — changes take effect within seconds without restarting the server.
|
|
|
|
Key server config options:
|
|
|
|
| Setting | Description |
|
|
|---|---|
|
|
| `api.host` / `api.port` | Bind address (default `127.0.0.1:3000`) |
|
|
| `api.authentication_strategies` | Auth methods: `jwt`, `mtls`, or both |
|
|
| `api.tls` | Optional HTTPS with cert/key/CA paths |
|
|
| `max_concurrent_runs` | Scheduler concurrency limit (default 5) |
|
|
| `[llm]`, `[sandbox]`, `[vars]` | Defaults applied to every run (overridable per-run) |
|
|
|
|
### Run lifecycle
|
|
|
|
1. **Submit** — `POST /api/v1/runs` with a Graphviz workflow source. The run is created with status `Queued` and the response returns immediately with the run ID.
|
|
2. **Schedule** — A background scheduler promotes queued runs to `Running` in FIFO order, up to the concurrency limit.
|
|
3. **Execute** — The engine walks the graph, streaming events to all subscribers.
|
|
4. **Complete** — The run transitions to `Completed`, `Failed`, or `Cancelled`.
|
|
|
|
### Event streaming
|
|
|
|
The API streams run events via [Server-Sent Events (SSE)](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events). Every significant action — stage starts, LLM calls, tool invocations, edge selections — is emitted as a structured JSON event. The web UI uses this endpoint for real-time run monitoring. Any HTTP client that supports SSE can subscribe. See the [run events endpoint](/api-reference/runs/stream-run-events) in the API reference.
|
|
|
|
### Human-in-the-loop
|
|
|
|
In API mode, human-in-the-loop questions are served over HTTP instead of terminal prompts. The engine blocks the current stage until an answer is received, then continues execution. See the [list questions](/api-reference/human-in-the-loop/list-run-questions) and [submit answer](/api-reference/human-in-the-loop/submit-run-answer) API reference pages.
|
|
|
|
### Authentication
|
|
|
|
API mode supports two authentication strategies, configurable in `settings.toml`:
|
|
|
|
- **JWT** — EdDSA-signed tokens (used by the web UI)
|
|
- **mTLS** — Mutual TLS with client certificates (used for service-to-service communication)
|
|
|
|
### Demo mode
|
|
|
|
Demo mode is per-request: send the `X-Fabro-Demo: 1` HTTP header to get static mock data with authentication disabled. The web UI sends this header automatically when configured with `FABRO_DEMO=1`. This lets you explore the UI without API keys or real workflow execution.
|
|
|
|
## Web UI
|
|
|
|
The web UI is a React app (`apps/fabro-web`) that connects to the API server. Start it alongside `fabro server start`:
|
|
|
|
```bash
|
|
fabro server start # API on port 3000
|
|
cd apps/fabro-web && bun run dev # rebuilds web assets on change; refresh the browser
|
|
```
|
|
|
|
The UI provides:
|
|
- **Run board** — List and monitor all runs
|
|
- **Run detail** — Real-time stage progress, event stream, diffs, usage stats
|
|
- **Start new run** — Submit a Graphviz workflow from the browser
|
|
- **Human-in-the-loop** — Answer agent questions through the web interface
|
|
- **Sessions** — Interactive chat interface (coming soon)
|
|
- **Insights** — SQL-based analysis across runs via DuckDB
|
|
|
|
## Comparison
|
|
|
|
See [Server Mode](/administration/deploy-server#standalone-vs-server-mode) for a full feature comparison between standalone and server mode.
|