mirror of
https://github.com/fabro-sh/fabro.git
synced 2026-08-28 05:27:41 +00:00
41f7b0cda6
Restructure the flat `serve` command into a nested `server start` subcommand, following the existing namespace pattern (system prune, repo init, etc.). Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
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`) backed by SQLite for run persistence. Runs are submitted via the REST API and executed asynchronously.
|
|
|
|
### Configuration
|
|
|
|
The server reads `~/.fabro/server.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 `server.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 # Web UI on port 5173
|
|
```
|
|
|
|
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.
|