Architecture overview¶
This page is for anyone who wants a map of DiAGRI before reading the code or the other design pages. It shows the parts, which part owns which state, how the parts talk to each other, and how one research round moves through them.
Status. Everything here has been tested on the simulated AC5 only, and
growbridge servedoes not yet start or reach every part shown. Each section says which. The full list is in Status and known limitations.
The parts¶
flowchart TD
OP(["Operator"])
subgraph MODEL["Model roles: read data, hand in drafts"]
ORC["Orchestrator"]
PLN["Planner"]
RES["Researcher"]
end
WB["Workbench<br/>JSON routes under /wb"]
WF["Workflow service and task board<br/>owns round, stage and task state"]
subgraph PROG["Deterministic programs: never call a model"]
EXE["Executor"]
OBS["Observer and notifier"]
end
CTL["Control service<br/>the only BLE writer"]
ARC["Project archive<br/>owns records"]
AC5[("AC5 controller")]
CMP["Compute service<br/>started when fully configured"]
MON["External monitor<br/>not started by serve"]
OP -->|"approve, start, take over, resume"| WB
WB -->|"stage commands"| WF
WB -->|"manual writes, irrigate"| CTL
ORC -->|"research tasks"| WF
PLN -->|"run-sheet drafts"| WF
RES -->|"snapshot frozen, report published"| WF
RES -->|"snapshots, reports"| ARC
WF -->|"grants and hands over write rights"| CTL
EXE -->|"reads the active stage, reports stage events"| WF
EXE -->|"submit"| CTL
OBS -->|"alert pause"| WF
OBS -->|"alerts, daily report"| OP
CTL -->|"BLE write and read-back"| AC5
CTL -->|"action records"| ARC
RES -.->|"compute jobs"| CMP
OBS -.->|"heartbeat"| MON
Solid arrows are paths that run inside the daemon. The two dashed arrows are optional. The compute arrow leads to a part that exists in the code and its tests but is not started by growbridge serve: cli.py calls build_runtime without a compute backend, so Runtime.compute is None. The heartbeat arrow runs only when both heartbeat URLs are set in the environment; otherwise Runtime.monitor is None and the runtime raises the standing warning monitor_unconfigured.
The workbench is the operator's HTTP interface: JSON routes under /wb in workbench/api.py. The operator console, the page at /workbench under src/growbridge/web/workbench/, calls these routes and nothing else. The page in src/growbridge/web/ at / is the bridge dashboard and never calls /wb.
Two rules give the diagram its shape.
No model role can reach the device or a stage. A model can be wrong, and it can be misled by text it reads. So the four model roles only get tools that read data and file drafts. Each role's tool list is fixed in ROLE_TOOLS, and every stage or device tool name is refused through CONTROL_TOOLS, whatever the configuration says (agents/tools.py). See The agents.
Every write to the device goes through one checkpoint. The executor and the operator both write through the control service, which checks the write right, records the intent, sends, and reads back. See Control and safety model.
Who owns what¶
Each kind of state has one owner. Every other part reads it through the owner, or asks the owner to change it.
The reason is recovery. If two parts could both change a stage's state, a crash between their two updates would leave them disagreeing about whether the stage is paused. With one owner there is one answer, and it is saved in one transaction.
| State | Owner | In code | Database file |
|---|---|---|---|
| Projects, protocols, rounds, stages, approvals, stage history | workflow service | WorkflowService, WorkflowStore |
workflow.sqlite3 |
| Research tasks | the workflow service's task board | TaskBoard |
workflow.sqlite3 |
| Operators and their sessions | workbench | Operators |
workflow.sqlite3 |
| Write host, recovery number, write rights, action ledger, safety configuration, interlock flag | control service | ControlService, Ledger |
control.sqlite3 |
| Samples, action records, measurements, evidence cards, snapshots, artifacts | project archive | Archive |
archive.sqlite3 and the archive/ folder |
| Alerts, notification outbox, daily reports | observer and notifier | AlertBook, Outbox, ReportStore |
observer.sqlite3 |
| Model-call budget, dispatch claims, confirmatory runs, holdout registry | the model-role runtime | CallBudget, Dispatcher, ConfirmatoryRunner, HoldoutRegistry |
agents.sqlite3 |
| Compute attempts and quota | compute service | ComputeService |
compute.sqlite3 |
An example of ownership at work. The executor reads the device back and finds that someone changed the light on the AC5 panel. It does not pause the stage. It reports an EXTERNAL_CHANGE stage event. The workflow service decides that a running stage becomes paused, and asks the control service to revoke the stage write right. Three owners, each changing only its own state.
How the parts talk¶
The services in the control loop know each other only as protocols, never as classes. The protocols are in ports.py:
| Protocol | Implemented by | Used by | What crosses it |
|---|---|---|---|
StagePort |
WorkflowService |
executor, observer | active_stage() returns a StageRuntime; report() takes a StageEvent |
ControlPort |
ControlService |
workflow service, executor, workbench | rights (grant, handover), writes (submit, irrigate, pump_off), reads (read_state, differences, readings) |
WriteTransport |
the BLE transports | control service, through the bridge | send, and halt() for old-write-stop confirmation |
RecordSink |
Archive |
control service | append_action, append_sample |
The data that crosses these protocols is defined in two files: ports.py (Actor, ActionRequest, StageRuntime, StageEvent, Difference) and archive/models.py (RunSheet, ActionRecord, WriteRight, SafetyConfig and the rest). A refusal is always Denied(code) with a machine-readable code. The codes are listed in Denial codes and stage events.
Why protocols: the executor is built with a ControlPort and a StagePort and nothing else, so it has no way to send a BLE command or change a stage except through them. The same protocols let the tests swap a service for a simulated one.
Two parts sit at the edge and are handed the service objects themselves: the workbench routes and the tool handlers of the model roles. They call public methods of WorkflowService, ControlService, Archive and TaskBoard. They still cannot skip a check, because the checks are inside those methods.
Identity never comes from the caller's data. An Actor is built by the server from an operator session or a role token (workbench/api.py), or fixed in code for a model role (actor_for in agents/handlers_common.py). A field such as role or approved in a tool input fails validation.
All of this is wired in one function, build_runtime in runtime.py.
One process, one database file per owner¶
growbridge serve with auto_research = true runs everything in one process and one event loop (_serve_auto_research in cli.py):
- The tick, once a second (
TICK_SECONDS).Runtime.tickruns nine steps in a fixed order:archive,executor,recovery,observer,outbox,tasks,report,backup,health. Each step is guarded: a step that fails raises an alert and the later steps still run. The tick never calls a model. - The model-role loop, every 30 seconds (
AGENT_SECONDS), only whenrolesare configured and a model client can be built. It runs each open research task once. A failure here becomes a task that needs attention and an alert. It never fails a tick. - The HTTP listeners: the main one on loopback, plus the on-site one when
lan_bindandlan_portare set.
One process keeps the single checkpoint simple. The control service puts hand-overs and writes in order with one in-process lock, and a daemon.lock file keeps a second daemon off the same data directory.
Under data_dir there are six SQLite files, one per owner in the table above (DATABASES in runtime.py), next to the bridge-only daemon's sample history growbridge.sqlite3. Each service is given its own Database object and no other, so the ownership rule is visible in the wiring and not only a convention.
The architecture document goes further and gives each service its own system account (sections 4.7 and 10). The code does not do that: it is one process under one account. The separation that exists in code is the protocols, the server-side identities, the per-owner files, and the sandbox for model-written analysis code.
One research round through the parts¶
- An operator identity creates the project, saves the research protocol and creates the round (
create_project,save_protocol,create_round). The round isdesigning. The operator then sets the project's call budget and states the goal, which becomes the first orchestrator task. Through/wbroutes, tested with an in-process HTTP client.simulatecalls the services directly and states no goal. - The orchestrator hands a task to the planner. The planner validates a run sheet and files it with
save_plan_draft, which callssubmit_run_sheet. The stage ispending_reviewand the roundstage_review. The model part runs in tests only;simulatefiles the run sheet with a direct call. - The operator approves and starts the stage in the workbench (
approve,start_stage). The workflow service asks the control service for a stage write right and a care write right. The stage isrunningand the roundstage_running. - Every second the executor reads the active stage, evaluates the run sheet and submits writes to the control service, which checks, records, sends and reads back. Action records and samples go to the archive. The observer raises alerts, and the runtime renders the daily report.
- When the run sheet's duration is over, the executor reports
END_CONDITION_MET, carries out the end actions and reportsEND_ACTIONS. The stage isended. The round returns tostage_reviewif the protocol has more stages, and otherwise moves todata_verification. - The researcher freezes the stage's data with
freeze_dataset. If the snapshot is complete and verifies, the round moves toanalysis. Tests only. - The researcher publishes the report with
publish_research_report. A final report moves the round todelivered. Tests only.
What has run only in tests. Through /wb an operator does step 1 and steps 3 to 5, and can stop a stage, choose what follows, or abort the round. The model roles do steps 2, 6 and 7 once a budget is set and a goal is stated. No real model has ever done so: test_e2e_http_round.py takes a whole round through the routes with a scripted model and an in-process HTTP client. growbridge simulate (simulate_stage in runtime.py) runs steps 1 to 5 by calling the services directly. No CLI command starts a round.
The states, and who may trigger each transition, are on Workflow and state machines.
Where the design is written down¶
The architecture document (in Chinese) holds the full reasoning: sections 1 to 4 for the overview, 5 to 10 for the details, Appendix B for the state tables. This wiki describes the code as it is. Where the two differ, the page says so.
See also¶
- The agents
- Control and safety model
- Workflow and state machines
- Data, archive and traceability
- Code structure and extension points
- Status and known limitations
- Glossary
Pages were last checked against the code on 2026-11-11. DiAGRI mode has been tested on a simulated AC5 only: see Status and known limitations. To change a page, read how this wiki is edited first.