Refactor: manual operator reporting as primary fault ingestion path

[AdamRidene]

Problem

Hackathon feedback: the target audience is maintenance managers in mid-size Tunisian plants (textile, agro-food, plastics, mechanical) where machines are 10-30 years old with no PLCs, no SCADA, no digital connectivity. The system was originally built assuming MQTT as the default ingestion path, with manual input treated as a SIM_FAULTS demo button -- the exact opposite of what real users need.

Solution

Invert the architecture: make manual operator reporting the primary (and default) path, and treat MQTT as an optional Tier 3 upgrade.

Three-tier ingestion model

Tier	Path	Hardware	Default
1	Operator phone -> /operator/report -> REST API	None	Default
2	External system -> POST /api/faults	None	Available
3	ESP32/PLC -> MQTT -> listener	~$20 ESP32	Opt-in

Key changes

• source field on WorkOrder and FaultIn schemas (defaults to "manual"), tracked through the entire pipeline so operators and MQTT-sourced faults are distinguishable
• Simulate button removed from both the React dashboard and the built-in dashboard; replaced with a link to /operator/report
• Mobile-optimized operator page (/operator/report): pure HTML/CSS/JS, 3-tap submission (select machine -> tap fault code -> submit), RTL-ready, dark mode by default, loads machines and fault codes from API
• Dashboard sidebar card pointing to /operator/report with QR-friendly link
• ManualFaultForm refactored: always visible (no collapsible toggle), machine field changed from free-text to <select> dropdown populated from GET /api/machines
• SourceBadge component: shows manual (amber) or mqtt (blue) in work order table rows
• MQTT made purely opt-in: default broker URL changed to "", listener only starts when non-empty, health endpoint returns {"configured": false, "connected": false}, dashboard health bar shows muted grey dot
• GET /api/fault-codes endpoint with in-memory caching to populate hints
• Fault code hints filtered by selected machine on the operator page
• Duplicate detection: handle_fault checks for an existing work order with the same (machine, fault_code) within a 30-second window before creating a new one
• Landing page copy updated: step 1 description and feature 5 explicitly state "No sensors, no PLCs, no hardware required"
• FAQ Q4 describes the three tiers
• i18n keys updated in EN/FR/AR
• README updated with tier table under "What is TORQ"

Files changed

 README.md                          |  18 +++-
 src/torq/agent/schemas.py          |   1 +
 src/torq/api/main.py               |  38 +++++---
 src/torq/api/routes.py             |  49 +++++++---
 src/torq/config.py                 |   9 +--
 src/torq/db/models.py              |  21 ++++-
 src/torq/events/listener.py        |   1 +
 src/torq/operator/report.html      | 215 ++++++++++++++++++++++++++++++
 src/torq/pipeline.py               |   9 ++-
 src/torq/workorder/generate.py     |   4 +-
 uv.lock                            |  11 ++
 web/src/api.js                     |   2 +
 web/src/i18n.jsx                   |  30 +++--
 web/src/pages/Dashboard.jsx        |  79 ++++++------
 web/src/pages/Dashboard.module.css | 145 ++++++++++++++++-----
 15 files changed, 514 insertions(+), 118 deletions(-)

Verification

• All 71 existing tests pass
• Frontend builds clean with Vite
• Tested both ingestion paths: manual form and MQTT listener