Architecture

Open-FDD is a container stack for building telemetry, semantic modeling, and supervisory HVAC fault detection.

Layer Role
openfdd-fieldbus / split connectors On-prem BACnet/Modbus → MQTTS; Haystack HTTP (hisRead) separate — see path-split ADR
openfdd-mqtt Mosquitto MQTTS broker (hub or campus)
openfdd-central Parquet historian, DataFusion SQL FDD + analytics, JWT REST
openfdd-web React SPA (Overview, Lab, RCx, Reports) — same-origin /api
openfdd-mcp (optional) Read-first stdio tools for external agents

Product FDD and Overview analytics are DataFusion SQL only. PyPI open-fdd (pandas / ECM) is third-party oracle tooling — not the request path.

Guides

Topic Document
Services Images and compose roles
Data flow Drivers → model → historian → FDD → UI
Storage & DataFusion Parquet historian and SQL rules
Historian architecture Hive layout, compaction, scale honesty
Historian path split ADR OT MQTTS vs Haystack hisRead; durability metrics (#1017 L1)
DataFrame API migration inventory SQL-string density for #1078 runtime migration
DataFusion-first Computation boundary
Job workspaces Durable Jobs under workspace/jobs/
Analytics boundary Typed DF analytics vs React
VAV health matrix Cohort broken / comfort / rogue scores
Multi-client hosting Tenant isolation sketch
Data model graph Haystack / RDF contract

Operator mental model

  1. Map once — package zip stamps Haystack roles → SQL columns (sat, oa_t, fan_status, …).
  2. Ingest — live MQTTS or CSV/package import into Parquet under OPENFDD_STORAGE_URL.
  3. Detect — Lab / POST /api/fdd/run evaluates sql_rules/registry.yaml; Overview tables call /api/analytics/*.
  4. Act — Reports, health matrices, RCx Plots; agents use JWT REST or MCP.

LAN / VPN / OT-oriented. Do not expose central on the public internet without an independent security review.

Table of contents