init app

proposed-plan.md

@@ -0,0 +1,44 @@
+# 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.