NGX-http-Monitoring-Client/proposed-plan.md

NGX HTTP Monitoring Client App Plan

Summary

Build a polished Jetpack Compose operations app for monitoring 20+ Nginx monitoring-module servers. The app is local-first, stores encrypted per-server credentials, uses foreground SSE streams for all enabled servers while the app is open, and uses Android-friendly periodic background checks for alerts.

Key Changes

• Add app architecture with Compose, Navigation, ViewModels, Room, WorkManager, OkHttp SSE, kotlinx serialization, and encrypted credential storage.
• Create core models: ServerProfile, AuthConfig, MonitorSnapshot, MetricSummary, AlertRule, AlertEvent, and ServerTag.
• Support /monitor/api, /monitor/health, and /monitor/live; send Basic Auth and X-Monitor-Token when configured.
• Add first-run and server setup flow: name, base URL, tags, favorite flag, token, optional Basic Auth, opt-in HTTP toggle, and test connection.
• Store derived metric summaries every 1 minute and full raw JSON snapshots every 15 minutes, retained for 30 days.

App Experience

• Dashboard: fleet health counts, search, tags, favorites, critical-first sorting, stale/offline indicators, and compact server cards with CPU, memory, disk, request rate, latency, 4xx/5xx, active connections, and last update.
• Server detail: live overview plus tabs for System, Nginx, Requests, Network, Disk, Processes, Upstreams, History, Alerts, and Settings.
• Alerts: ship global defaults with per-server overrides for unreachable/stale server, CPU/memory/disk pressure, high 5xx, high latency, and auth/API failures.
• Background monitoring: WorkManager periodic checks using /monitor/health and lightweight API fetches; local notifications fire only on state changes or sustained rule breaches.
• Security UX: HTTPS by default; HTTP allowed only per server with a visible warning. Never log tokens, Basic Auth, or URLs containing secrets.

Failure Handling

• Treat missing JSON fields as unavailable collectors, not crashes.
• Show clear states for 401, 403, 404, 429, timeout, TLS failure, malformed JSON, and stale SSE.
• Foreground SSE opens one stream per enabled server; if a stream fails repeatedly, fall back to staggered JSON polling for that server and show degraded-live status.
• Apply retry backoff and avoid notification spam with cooldowns and alert state tracking.

Test Plan

• Unit tests for JSON parsing with missing collectors, auth header creation, alert evaluation, retention pruning, URL validation, and HTTP opt-in rules.
• Repository tests with fake monitor responses for /monitor/api, /monitor/health, and SSE events.
• Compose UI tests for empty state, add server, dashboard filtering/sorting, server detail tabs, and alert rule editing.
• Background-worker tests for periodic checks, notification deduping, and failed-auth handling.

Assumptions

• No cloud backend or account sync in v1; all data stays on the phone.
• Android minSdk remains 24.
• “SSE everywhere” means all enabled servers while the app is foregrounded; background monitoring uses periodic checks for Android reliability.
• Long history means balanced local retention, not every SSE payload forever.