System Architecture
Verdify is deliberately boring infrastructure around a physical greenhouse. One local VM runs the data plane, planning tools, dashboards, API, and static-site publisher. The ESP32 sits at the edge and owns the live control loop. External services are used where they are useful, but the greenhouse should not depend on the public website or a model route to keep running.
This page owns the component map and data flow. The relay safety argument belongs on Why the AI Does Not Control Relays, and the planning workflow belongs on Planning Loop.
Runtime Shape
One air volume with zones, crops, sensors, heaters, fans, venting, fog, misting, grow lights, irrigation, and solar exposure.
Local firmware reads greenhouse state, exposes configured values, and drives physical equipment.
Maintains the ESPHome connection, records state changes, runs scheduled enrichment jobs, and dispatches validated setpoints.
Stores telemetry, equipment state, forecasts, setpoint records, plan journals, scorecards, and derived views.
Expose bounded read/write tools, assemble planning context, and write plan intent through audited tool calls.
Publishes Quartz pages, Grafana panels, generated plan archives, API snapshots, sample CSVs, and operational lessons.
Data Flow
ESPHome state changes report climate, equipment, configured values, diagnostics, and controller state.
The ingestor writes raw and normalized rows into TimescaleDB, then periodic jobs enrich weather, energy, water, forecasts, alerts, and summaries.
Database views and functions turn raw telemetry into compliance, stress, forecast accountability, cost, water, and equipment-runtime evidence.
The AI planning agent reads the generated context window and writes bounded plan intent through MCP tools.
The ingestor resolves the active plan, pushes changed values through the ESPHome native API, and records confirmation from firmware readbacks.
Grafana, generated Markdown, static assets, and public API exports make the evidence inspectable without exposing the private control surface.
The dispatcher runs on a five-minute cadence and also has an immediate reconciliation path after ESP32 reconnect. Detailed parameter ownership, clamps, and readback status are maintained on AI Tunables Traceability and Planning Loop.
Boundaries
Physical control should continue if public publishing, model routing, or dashboard rendering fails.
The VM is the operational hub: it reads the greenhouse, stores the audit trail, dispatches plan intent, and builds public evidence.
The planner can propose tactics and hypotheses only through validated tools and audited trigger metadata.
Readers get live proof and generated records; they do not get write access to the greenhouse.
Implementation Notes
The current production path uses ESPHome native API push plus configured-value readback confirmation for setpoint delivery. HTTP /setpoints compatibility endpoints still exist for diagnostics and recovery tooling; they are not the running ESP32 polling path.
The ingestor task loop includes scheduled jobs for water flow, materialized views, Shelly energy, Tempest weather, Home Assistant sensors, alerting, setpoint dispatch, setpoint confirmation, forecast sync/actions/deviation checks, daily summaries, grow-light rollups, planning heartbeat, midnight watch, and public evidence sampling. The exact object counts and table/view/function inventory belong on Data Model, where they are easier to keep current.
Reference Implementation Notes
Verdify is not a turnkey kit today. These notes are a public-safe reference implementation path: enough to understand and rebuild the pattern, without pretending the exact greenhouse wiring is safe to copy blindly.
The safe pattern is:
deterministic edge controller + time-series database + bounded AI planner + public scorecard
The exact relay map, water pressure, gas heat, wiring, breaker layout, and fail-safes need a local electrician/grower/operator review before anyone copies them.
Hardware Shape
ESPHome firmware, encrypted native API, relay outputs, Modbus inputs, ADC inputs, direct setpoint push, and firmware readbacks.
Temperature and relative humidity by zone; VPD is computed from temperature and humidity.
Soil moisture, temperature, and EC where installed.
pH, EC, TDS, ORP, and solution temperature through Home Assistant.
Relay-backed equipment controlled by ESP32 firmware, not by the LLM.
Outdoor weather, forecast context, and resource cost/accountability.
See Equipment Inventory for the public-safe equipment inventory and high-level actuator list.
Runtime Stack
Reads sensors and enforces relay state in local firmware.
Subscribes to ESPHome state, writes TimescaleDB, runs dispatcher and alert tasks.
Stores climate, equipment, forecast, energy, water, plans, lessons, and scorecards.
Gives the planner typed tools for state, forecast, scorecards, alerts, lessons, and tunables.
Reads greenhouse context and writes tactical plans and hypotheses using the planner context window.
Publishes public pages, dashboards, daily plans, and sample datasets.
The exact tactical parameters the AI planning agent is allowed to write are documented in AI Tunables Traceability.
Database Overview
| Surface | Tables/views | Purpose |
|---|---|---|
| Climate | climate, v_greenhouse_now, v_setpoint_compliance | What the greenhouse experienced. |
| Equipment | equipment_state, v_equipment_now, v_state_durations | What the controller physically did. |
| Planning | plan_journal, setpoint_plan, v_active_plan | What the planner intended and what is active. |
| Scorecards | daily_summary, v_planner_performance, fn_planner_scorecard() | Whether the plan worked. |
| Lessons | planner_lessons plus generated lesson page | What future plans should remember. |
| Static context | site markdown bundled by context scripts | The greenhouse’s documented physical constraints, equipment, zones, crops, and lessons. |
| Evidence | v_forecast_plan_outcome_mart, sample CSV exports | Public audit artifacts. |
See Data Model for the broader table/view map.
See AI Tunables Traceability for the planner-writable registry: defaults, bounds, ownership, and relay/state-machine impact.
Example Plan JSON
This is a shortened representation of one plan. The real plan journal contains more context and waypoints.
{
"plan_id": "iris-20260429-0605",
"created_local": "2026-04-29 06:04",
"horizon_hours": 72,
"hypothesis": "Cool mixed-cloud day with a short dry solar window. Keep fog conservative and use moderate mist readiness only when observed VPD rises.",
"changed_tunables": [
{
"parameter": "mister_engage_kpa",
"old_value": 2.5,
"new_value": 1.6,
"expected_effect": "Reduce midday VPD-high stress without causing overnight VPD-low stress."
},
{
"parameter": "fog_escalation_kpa",
"old_value": 1.0,
"new_value": 0.85,
"expected_effect": "Reserve fog for real VPD breakout on a cool day."
}
],
"success_criteria": {
"both_axis_compliance_pct": 60,
"vpd_high_stress_h_max": 1.5,
"cost_total_usd_max": 7.0
}
}Example Scorecard JSON
{
"date": "2026-04-29",
"planner_score": 73.5,
"compliance_pct": 74.3,
"temp_compliance_pct": 86.2,
"vpd_compliance_pct": 84.8,
"total_stress_h": 6.93,
"heat_stress_h": 0.88,
"vpd_high_stress_h": 3.28,
"water_gal": 159.0,
"mister_water_gal": 37.0,
"cost_total": 4.42
}Live scorecards are available from the public read-only API, for example /api/v1/scorecard?date=2026-04-29.
What We Would Copy First
- Keep real-time control local and deterministic.
- Put every setpoint behind a typed registry with clamps and readbacks.
- Store raw telemetry and derived scorecards separately.
- Publish failures and stale-data states alongside success charts.
- Treat every plan as a hypothesis that must be scored against the next day.
Facts Owned Elsewhere
Why the AI is not the relay loop, and what happens when planner, network, sensor, dispatcher, or actuator paths fail.
Trigger context, MCP writes, prompt contracts, dispatcher delivery, journaling, and lessons.
Names, defaults, bounds, ownership, state-machine effects, and readback status.
Structure, zones, crops, equipment, lighting, water, and manual operating policy.
Route-level proof, utility timing, cost accounting, AI compute watts, sample exports, generated plans, and scorecards.
Deeper dives: Planning Loop - Safety Architecture - Data Model - Related Work - Baseline vs AI Planning Agent