Engineering problem
Provide a single CLI, health status for WAN/DNS/MAIN, an incident journal and Telegram notifications while keeping the data plane independent from the control-plane components.
Back to projects
CUDY Home Gateway
An OpenWrt home-gateway control plane for observing WAN, DNS and service health without becoming part of the network traffic path.
- Device
- CUDY TR3000 / OpenWrt
- Focus
- System Engineering · Observability
- Status
- 0.5.0-dev; v1.0.0 not accepted
PROBLEM & CONSTRAINTS
Monitoring must not become the cause of an outage.
A home gateway carries essential network traffic. Diagnostics and remote control are useful only when their failures cannot interrupt routing.
Constraints
- OpenWrt and BusyBox have limited resources and available runtime dependencies.
- PassWall2/Xray, DNS, nftables and Tailscale continue working without the control plane.
- No arbitrary remote shell or automatic MAIN switching.
- Passing host-side contract tests does not replace on-device validation.
ARCHITECTURE
Control plane is isolated from data plane.
Health normalizes observations, Incident Engine applies debounce/hysteresis, Projection creates events and a persistent queue decouples incident state from Telegram delivery. Control actions have a separate restricted path.
- control ≠ data plane
- debounce / hysteresis
- persistent journal
- delivery ≠ exactly-once
INCIDENT LIFECYCLE
Alerts follow confirmed state transitions.
An observation is not yet an incident: one short-lived probe failure must not become an immediate alert.
Observation
Health Core normalizes WAN, DNS, MAIN and other services into OK, DEGRADED, DOWN, UNKNOWN or MAINTENANCE, tracking external evidence freshness.
Confirmation
Incident Engine opens DEGRADED/DOWN after three consecutive observations; recovery to OK requires two observations.
Journal
OPEN, STATE_CHANGED and RECOVERED events are persisted for replay after a restart.
Projection and queue
Incident transitions become independent notification records. The queue keeps pending, inflight and terminal receipts for retry and recovery.
Delivery and follow-up
The notification adapter handles retry/backoff, HTTP 429 and ambiguous send outcomes. On-device LIVE acceptance remains a separate gate.
ENGINEERING DECISIONS
Fail-closed behavior matters more than automatic control.
The design reflects the constraints of the device and the trust boundary around remote administration.
Separate observation from routing
Telegram and health never decide the traffic path. A control-plane crash must not reconfigure the data plane.
Separate probes from incidents
Debounce, hysteresis and UNKNOWN/MAINTENANCE distinguish transient probe failures from persistent incidents.
Be explicit about at-least-once
Telegram sendMessage has no idempotency key. An ambiguous acknowledgment can still produce a duplicate; exactly-once is not claimed.
Reject a general-purpose remote shell
The management interface allows only predefined commands. Risky actions require distinct authorization and never belong in read-only diagnostics.
EVIDENCE & VALIDATION
Automated checks exist; full LIVE acceptance remains open.
The ACCEPTANCE matrix separates isolated contract evidence from current HEAD behavior on an actual OpenWrt router. This is not a stable v1.0.0 release.
The roadmap documents earlier on-device validation; those checks do not prove every change in the latest code.
Notification, incident and state contracts include automated fault-injection and recovery checks.
Actual delivery, reboot, persistence and recovery behavior still require on-device acceptance.
Source documents and evidence
LIMITATIONS
Implemented contracts are not the same as accepted operation.
The project is not presented as a production-ready stable release: critical validation gates remain open.
Telegram delivery is not exactly-once
An acknowledged message with a lost response may be sent again despite durable delivery receipts.
Full LIVE validation of current HEAD
OpenWrt TLS/SOCKS, worker/reboot behavior, flash persistence, sysupgrade and recovery need separate device-level checks.
Safe Actions and MAIN transactions
The 0.7 contracts are disabled by default and lack full LIVE approval; public 0.8 documentation covers a read-only planner only.
Stable v1.0.0
Critical acceptance gates, sustained observation and a reproducible recovery drill are still needed.
TAKEAWAYS
The project demonstrates engineering under uncertainty.
The value lies in clear responsibility boundaries, explicit states and evidence—not the number of Telegram commands or claims of full automation.
- Monitoring should never jeopardize the traffic it observes.
- Incident lifecycle and notification delivery have different guarantees and failure paths.
- An isolated PASS is not interchangeable with acceptance on the target device.
SOURCE & EVIDENCE
Architecture, constraints and open acceptance are documented.
The public repository includes the README, architectural decisions, incidents, notifications and the open ACCEPTANCE matrix.