AGENTS.md

1# Open-FDD React product UI agent guide
2 
3## Mission
4 
5Maintain React (`frontend/web`) as the sole production UI with domain authority
6on **central Rust + DataFusion SQL**. Python is oracle/characterization only.
7**No FastAPI sidecar.**
8 
9Phase 1+2 exits are approved. Phase 3 (edge/live streaming) is outlook-only —
10see `PHASE_3_READINESS.md`. Do not redesign BACnet/MQTT without explicit auth.
11 
12This file is the modernization-kit `AGENTS.md`. It does **not** replace
13[`openfdd_agent_spec/AGENTS.md`](../../openfdd_agent_spec/AGENTS.md) or the repo
14root [`AGENTS.md`](../../AGENTS.md).
15 
16## Mandatory skill + OS bootstrap (every UI PR)
17 
18Before editing React/product UI code, **read and follow** in order:
19 
201. Repo root [`AGENTS.md`](../../AGENTS.md)
212. [`openfdd_agent_spec/AGENTS.md`](../../openfdd_agent_spec/AGENTS.md) — product law,
22   ownership, PR protocol, Milestone skills
233. This file
244. [`AGENT_SKILL_BRIDGE.md`](AGENT_SKILL_BRIDGE.md) — which skill for which work
255. **[`openfdd_agent_spec/skills/openfdd-react-spa/SKILL.md`](../../openfdd_agent_spec/skills/openfdd-react-spa/SKILL.md)**
266. [`AGENT_EXECUTION_SYSTEM.md`](AGENT_EXECUTION_SYSTEM.md)
277. Current phase doc + [`docs/migration/react-rust/`](../../docs/migration/react-rust/)
28   ledgers
298. Matching skill from `openfdd_agent_spec/skills/` when the PR touches SQL FDD,
30   cookbooks, GHCR, ECM, or architecture ownership
31 
32Do not invent a React redesign. Match documented product behavior and API contracts.
33 
34## Open-FDD repository map
35 
36```text
37frontend/web/                    React SPA (sole production UI)
38services/central/                Rust browser API + jobs + FDD orchestration
39sql_rules/ + crates/fdd_*        DataFusion FDD / analytics
40docs/migration/react-rust/       Durable ledgers + Phase 3 readiness
41tools/open-fdd-modernization/    This program kit
42openfdd_agent_spec/              Engineering agent OS + Milestone skills
43open_fdd/                        PyPI oracle / ECM (not production FDD runtime)
44```
45 
46## Source-of-truth hierarchy
47 
481. Running React at the target viewport and state (product path).
492. Central `/api` contracts and ledgers under `docs/migration/react-rust/`.
503. Browser measurements and same-viewport screenshots when doing visual work.
514. Visual inference last — document uncertainty.
52 
53Document intentional differences. Prefer React + contract evidence.
54 
55## Required architecture (Open-FDD)
56 
57```text
58React SPA ── same-origin /api ── central Rust ── DataFusion SQL
59                                      │
60                                      ├── jobs / mappings / artifacts
61                                      └── fieldbus/MQTTS (unchanged)
62 
63Python ── oracle / characterization only (Phase 1)
64```
65 
66### React owns
67 
68- Layout, components, tabs, responsive behavior, visible UI state.
69- Form drafts, selections, open/closed panels, transient feedback.
70- Loading, empty, disconnected, validation, and error presentation.
71- Client downloads when no server authority is needed.
72 
73### central Rust owns
74 
75- APIs, authz, validation, durable jobs, persistence, orchestration.
76- Ingestion, package/ZIP defenses, exports, error envelopes.
77- Stable JSON contracts consumed by React.
78 
79### DataFusion / sql_rules owns
80 
81- Deterministic telemetry analytics and FDD rule execution.
82- Never silently fall back to pandas in production paths.
83 
84### Python oracle owns
85 
86- Characterization fixtures, cookbook parity, optional ECM honesty checks.
87- Never a browser-facing FastAPI or production UI dependency for React.
88 
89## React SPA skill law
90 
91Follow [`openfdd_agent_spec/skills/openfdd-react-spa/SKILL.md`](../../openfdd_agent_spec/skills/openfdd-react-spa/SKILL.md):
92 
931. Inspect before editing (inventory widgets, session keys, branches).
942. Build a parity contract before pixel chasing.
953. Measure the product UI when browser tools exist.
964. Separate domain logic into Rust/SQL — not TypeScript formulas.
975. Translate shareable session keys into explicit React/URL/server state
98   ([P1-M3-03](MILESTONE_PR_MATRIX.md)).
996. Verify with Vitest and Playwright where applicable.
100 
101For Open-FDD: **backend = `services/central` (Rust)**. Do not add a Python API sidecar.
102 
103## Migration workflow (bounded PRs)
104 
1051. Establish baseline (record viewport/fixture).
1062. Inventory navigation, controls, session keys, downloads.
1073. Capture visual/geometry specs (`LAYOUT_GEOMETRY.md` and ledgers).
1084. Define/version Rust contracts before coupling React.
1095. Implement React presentation only; reuse widgets from `frontend/web`.
1106. Compare (exact / numeric / temporal / interaction / visual / artifact /
111   security classes). UNKNOWN blocks DONE.
1127. Update ledgers + `openfdd_agent_spec/SESSION_LOG.md` /
113   `BUILD_CHECKPOINTS.md` when Phase 1 status changes.
1148. One milestone ID per PR; CodeRabbit; green CI; squash-merge; prune.
115 
116## State translation
117 
118| UI state | Destination |
119|---|---|
120| Current tab / section | URL + React router (`main_section`) |
121| Select / open panel | React local or URL state |
122| Shareable job/equipment/site | URL search params |
123| Calculation input | React form → Rust API |
124| Calculation result | Query/cache from `/api/*` |
125| Durable config / mapping | Rust jobs + FDD session-config |
126| Auth | Server-side JWT / session validation |
127 
128Do not store authoritative job/mapping state only in `localStorage`.
129 
130## Calculation rules
131 
132- No pandas logic in TypeScript.
133- No FastAPI bridge.
134- No silent SQL → pandas fallback.
135- Preserve BACnet write safety; React never touches BACnet wire.
136- Distinguish raw values from presentation rounding.
137 
138## Minimum test coverage
139 
140- Contract/health and typed client compile.
141- Widget/component interaction tests for new primitives.
142- Route refresh/back/deep-link for session translation.
143- Slice e2e for Jobs → upload → map → run (M4+) without Python UI container.
144- Parity evidence rows updated in the same PR.
145 
146## Definition of done (shell / slice)
147 
148- Inventoried workflow migrated or explicitly waived in ledgers.
149- React talks only to central `/api`.
150- Production React build + affected CI green.
151- Product UI compared at identical viewport/state when visual class applies.
152- Intentional differences documented in `DECISIONS.md`.
153 
154## Related program docs
155 
156See [`README.md`](README.md) and [`AGENT_SKILL_BRIDGE.md`](AGENT_SKILL_BRIDGE.md).
157