Repository map
Applies to release 3.18.1 · View source at the tag · Markdown
| Path | Responsibility |
|---|---|
| frontend/src | React, TypeScript and shadcn UI source; theme, adapter, planning and setup screens |
| frontend/scripts | Single-file packaging and reproducible browser verification |
| mcp-server | Optional local stdio MCP connector, scoped HA configuration tools and protocol tests |
| custom_components/crop_steering | HA config flow, entities, setup/strategy/run APIs, storage and sidebar registration |
| addons/f2_control | Companion controller app, hardware coordinator, runtime validation and tests |
| crop-steering-engine | Pure decision core and its tests; vendored copy must remain identical |
| www/dashboard.html | Generated static web application |
| custom_components/crop_steering/www/dashboard.html | Identical generated application served by the integration |
| addons/f2_control/www/public/dashboard.html | Identical generated application served through ingress |
| doctrine | The crop-steering doctrine pack for the optional AI brain: hand-edited rules, outputs generated and checked against the code by doctrine/tools/build_doctrine.py; nothing reads it yet |
| tests | Integration and repository contract tests |
| docs | Install, operation, architecture and release process |
| docs/README.md | The documentation index |
| docs/features | One page per 3.18 feature area: supply, timers, presets, history, alerts, calibration, system status, dashboards |
| docs/dev | Working notes for developers: design specs, implementation plans and review write-ups. Not operator documentation |
| docs/TESTING.md / docs/ENTITIES.md | Development checks and entity reference |
| docs/DOSING.md | The batch-tank dosing contract between the integration, the controller app and the dashboard: configuration, services, requests, the batch sequence, restart recovery and status |
| docs/NOTIFICATIONS.md | The contract for who gets which alerts on the phones: the kinds of alert, the site's one store, the services, the routing, and the controller's fallback to its own notify service |
| docs/error-codes.json | The one list of error codes (CS-101 …); docs/ERROR_CODES.md is written from it by scripts/render_error_codes.py, and the dashboard's Settings > Help page imports it |
| img | Screenshots used by the README and docs |
| repository.yaml | HA app repository discovery metadata; the controller app is installed from this repository only |
Edit source in frontend/src and run the build; do not hand-edit generated dashboards. Small old-name HTML files are intentional compatibility redirects. Runtime entity IDs, room prefixes and the f2_control app slug remain stable; friendly names can change without breaking references.
The integration owns plan/configuration storage and per-room run metadata. Run records retain dates, stable zone/sensor IDs and timestamped reference targets; sensor readings stay in HA Recorder, with bounded authenticated history retrieval. Comparison and runtime calculators do not call actuator services.
The controller reads one atomic, versioned strategy snapshot, validates freshness and runs the pure decision core before its hardware IO sequence. Configuration revision and controller acknowledgement are distinct so the UI cannot mistake a saved mapping for a running configuration.