monoadmin/the-other-dude
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs(11-02): complete frontend site list and detail pages plan

Browse Source 
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This commit is contained in:
Jason Staack
2026-03-18 21:48:51 -05:00
parent e8c69fb6a6
commit 6ccccb3902
4 changed files with 478 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

135
.planning/REQUIREMENTS.md Normal file
View File

@@ -0,0 +1,135 @@
# Requirements: TOD v9.7 — Tower & Site Management
**Defined:** 2026-03-18
**Core Value:** Operators can organize their MikroTik fleet by physical site, see tower-level health with sector/CPE views, and collect full wireless radio statistics — without disrupting the flat-list MSP workflow.
## v9.7 Requirements
### Sites
- [x] **SITE-01**: Operator can create a site with name, coordinates (lat/lng), address, elevation, and notes
- [x] **SITE-02**: Operator can edit and delete sites
- [ ] **SITE-03**: Operator can assign devices to a site (single and bulk assignment)
- [ ] **SITE-04**: Operator can remove a device from a site (device returns to "unassigned")
- [x] **SITE-05**: Devices without a site assignment continue to work normally in all existing views
- [x] **SITE-06**: Sites are tenant-scoped — each tenant manages their own sites independently
### Site Dashboard
- [x] **DASH-01**: Operator can view a site list page showing all sites with health rollup (device count, online %, alert count)
- [ ] **DASH-02**: Operator can click into a site to see a device health grid (status, CPU, memory, uptime for all devices at that site)
- [ ] **DASH-03**: Operator can switch to a sector-centric view within a site dashboard showing APs grouped by sector with connected CPEs, aggregate bandwidth, and signal distribution
- [ ] **DASH-04**: Site dashboard shows wireless link topology (which CPEs connect to which APs) with signal quality indicators
### Sectors
- [ ] **SECT-01**: Operator can define sectors within a site (name, optional azimuth/bearing)
- [ ] **SECT-02**: Operator can assign APs to sectors
- [ ] **SECT-03**: Sector view shows aggregate client count, bandwidth, and signal statistics per sector
### Wireless Collection
- [ ] **WRCL-01**: Poller collects per-client registration table data from APs (MAC, signal, CCQ, TX/RX rates, distance, uptime) on a 5-minute cadence
- [ ] **WRCL-02**: Poller collects per-interface RF stats (noise floor, channel width, TX power, registered client count) via monitor command
- [ ] **WRCL-03**: Per-client wireless data publishes to a dedicated NATS stream (separate from DEVICE_EVENTS) to prevent stream saturation
- [ ] **WRCL-04**: Per-client wireless data stores in a dedicated hypertable with 30-day retention (separate from existing wireless_metrics)
- [ ] **WRCL-05**: Poller handles RouterOS v6/v7 field differences gracefully (CCQ absent in v7 wifi package)
- [ ] **WRCL-06**: Signal strength parsing handles RouterOS format variations (e.g., `-67@5GHz` suffix)
### Link Discovery
- [ ] **LINK-01**: Backend auto-discovers AP-CPE relationships by matching registration table MAC addresses against known device interface MACs
- [ ] **LINK-02**: Link state uses a temporal state machine (discovered -> active -> degraded -> down -> stale) with consecutive-miss threshold to prevent false flapping
- [ ] **LINK-03**: Wireless links are stored in a materialized table for fast dashboard queries
- [ ] **LINK-04**: Unmanaged wireless clients (MACs not matching any TOD device) are displayed as "unknown clients" with signal/rate data
### Wireless UI
- [ ] **WRUI-01**: Device detail page shows a per-station wireless table (connected clients with MAC, signal, CCQ, TX/RX rates, distance, uptime)
- [ ] **WRUI-02**: Device detail page shows per-interface RF stats (noise floor, channel width, TX power)
- [ ] **WRUI-03**: Wireless links page shows all discovered AP-CPE relationships with signal quality and link state
### Signal Trending
- [ ] **TRND-01**: Operator can view per-station signal history charts showing signal strength over time
- [ ] **TRND-02**: System detects signal degradation trends (e.g., "signal dropped 8dB over 2 weeks")
### Site Alerting
- [ ] **ALRT-01**: Operator can create site-scoped alert rules (e.g., "alert when >20% of devices at this site go offline")
- [ ] **ALRT-02**: Operator can create sector-scoped alert rules (e.g., "alert when sector average signal drops below -75dBm")
## Future Requirements
### Map View
- **MAP-01**: Operator can view sites on a geographic map with health-status-colored markers
- **MAP-02**: Operator can click a map marker to drill into the site dashboard
### Advanced Wireless
- **ADV-01**: Cross-reference wireless anomalies with config change timeline
- **ADV-02**: CAPsMAN read-only discovery (discover CAPsMAN-managed APs and display status)
- **ADV-03**: On-demand spectral scan trigger with result display
### Config Restore (deferred from v9.6)
- **REST-01**: User can restore a config snapshot to a router via SSH
- **REST-02**: Restore confirmation dialog with diff preview
## Out of Scope
| Feature | Reason |
|---------|--------|
| Map/geo visualization | Deferred to future milestone — adds tile provider complexity, dashboards deliver value faster |
| Config restore via UI | Deferred from v9.6 — still out of scope |
| Subscriber/customer management | BSS territory (Sonar/Powercode) — TOD is NMS, not billing |
| RF planning / link budget calculator | Dedicated RF planning tools exist — TOD monitors deployed infrastructure |
| Automated radio parameter changes | Dangerous in production WISPs — TOD provides visibility, not automation |
| Real-time spectrum analyzer | Requires continuous high-frequency polling — offer on-demand scan instead (future) |
| CAPsMAN configuration management | Complex and version-sensitive — read-only discovery deferred |
| Spectral scan during automated polling | Takes interface offline (destructive) — never auto-poll |
## Traceability
| Requirement | Phase | Status |
|-------------|-------|--------|
| SITE-01 | Phase 11 | Complete |
| SITE-02 | Phase 11 | Complete |
| SITE-03 | Phase 11 | Pending |
| SITE-04 | Phase 11 | Pending |
| SITE-05 | Phase 11 | Complete |
| SITE-06 | Phase 11 | Complete |
| DASH-01 | Phase 11 | Complete |
| DASH-02 | Phase 14 | Pending |
| DASH-03 | Phase 14 | Pending |
| DASH-04 | Phase 14 | Pending |
| SECT-01 | Phase 14 | Pending |
| SECT-02 | Phase 14 | Pending |
| SECT-03 | Phase 14 | Pending |
| WRCL-01 | Phase 12 | Pending |
| WRCL-02 | Phase 12 | Pending |
| WRCL-03 | Phase 12 | Pending |
| WRCL-04 | Phase 12 | Pending |
| WRCL-05 | Phase 12 | Pending |
| WRCL-06 | Phase 12 | Pending |
| LINK-01 | Phase 13 | Pending |
| LINK-02 | Phase 13 | Pending |
| LINK-03 | Phase 13 | Pending |
| LINK-04 | Phase 13 | Pending |
| WRUI-01 | Phase 14 | Pending |
| WRUI-02 | Phase 14 | Pending |
| WRUI-03 | Phase 14 | Pending |
| TRND-01 | Phase 15 | Pending |
| TRND-02 | Phase 15 | Pending |
| ALRT-01 | Phase 15 | Pending |
| ALRT-02 | Phase 15 | Pending |
**Coverage:**
- v9.7 requirements: 30 total
- Mapped to phases: 30
- Unmapped: 0
---
*Requirements defined: 2026-03-18*
*Last updated: 2026-03-18 after roadmap creation*

154
.planning/ROADMAP.md Normal file
View File

@@ -0,0 +1,154 @@
# Roadmap: TOD v9.7 — Tower & Site Management
## Overview
v9.7 transforms TOD from a flat device list into a site-aware fleet management platform. The build follows strict data flow dependencies: site data model first (immediately useful, no poller changes), then per-client wireless collection in the Go poller, then backend ingestion and link discovery, then the full site dashboard and wireless UI, and finally signal trending and alerting which require accumulated data. Each phase delivers a coherent, verifiable capability that unblocks the next.
## Milestones
- **v9.6 Config Backup** - Phases 1-10 (in progress)
- **v9.7 Tower & Site Management** - Phases 11-15 (planned)
## Phases
<details>
<summary>v9.6 Config Backup & Change Tracking (Phases 1-10)</summary>
- [x] **Phase 1: Database Schema** - Config snapshot, diff, and change tables with encryption and RLS (completed 2026-03-13)
- [x] **Phase 2: Poller Config Collection** - SSH export, normalization, and NATS publishing from Go poller (completed 2026-03-13)
- [ ] **Phase 3: Snapshot Ingestion** - Backend NATS subscriber stores snapshots with SHA256 deduplication
- [x] **Phase 4: Manual Backup Trigger** - API endpoint for on-demand config backup via poller (completed 2026-03-13)
- [x] **Phase 5: Diff Engine** - Unified diff generation and structured change parsing (completed 2026-03-13)
- [x] **Phase 6: History API** - REST endpoints for timeline, snapshot view, and diff retrieval with RBAC (completed 2026-03-13)
- [x] **Phase 7: Config History UI** - Timeline section on device page with change summaries (completed 2026-03-13)
- [ ] **Phase 8: Diff Viewer & Download** - Unified diff display with syntax highlighting and .rsc download
- [x] **Phase 9: Retention & Cleanup** - 90-day retention policy with automatic snapshot deletion (completed 2026-03-13)
- [x] **Phase 10: Audit & Observability** - Audit event logging for all config backup operations (completed 2026-03-13)
</details>
### v9.7 Tower & Site Management (Phases 11-15)
**Phase Numbering:**
- Continues from v9.6 (ended at Phase 10)
- Integer phases (11, 12, 13): Planned milestone work
- Decimal phases (11.1, 11.2): Urgent insertions (marked with INSERTED)
- [ ] **Phase 11: Site Data Model + Foundation** - Sites CRUD, device assignment, site list with health rollup
- [ ] **Phase 12: Per-Client Wireless Collection** - Poller extension to collect registration table and per-interface RF stats
- [ ] **Phase 13: Link Discovery + Registration Ingestion** - Backend NATS consumer, MAC resolution, AP-CPE link state machine
- [ ] **Phase 14: Site Dashboard + Sector Views + Wireless UI** - Site detail page, sector-centric view, per-station wireless tables
- [ ] **Phase 15: Signal Trending + Site Alerting** - Signal history charts, degradation detection, site/sector alert rules
## Phase Details
### Phase 11: Site Data Model + Foundation
**Goal**: Operators can organize devices by physical site and see a site list with aggregate health — without disrupting the existing flat-list workflow
**Depends on**: Nothing (first phase of v9.7; existing v9.6 foundation)
**Requirements**: SITE-01, SITE-02, SITE-03, SITE-04, SITE-05, SITE-06, DASH-01
**Success Criteria** (what must be TRUE):
1. Operator can create, edit, and delete a site with name, coordinates, address, elevation, and notes
2. Operator can assign one or many devices to a site, and remove a device back to "unassigned"
3. Site list page shows all tenant sites with device count, online percentage, and alert count
4. Devices without a site assignment work identically in all existing views (device list, device detail, remote access, config backup)
5. Sites are tenant-scoped — one tenant cannot see or modify another tenant's sites
**Plans:** 2/3 plans executed
Plans:
- [ ] 11-01-PLAN.md — Backend data model, migration, service, and REST API for sites
- [ ] 11-02-PLAN.md — Frontend site list page, CRUD dialogs, and navigation integration
- [ ] 11-03-PLAN.md — Device-to-site assignment UI and fleet table site column
### Phase 12: Per-Client Wireless Collection
**Goal**: The Go poller collects per-client registration table data and per-interface RF stats from all wireless devices, publishing to a dedicated NATS stream
**Depends on**: Phase 11 (schema for wireless_registrations hypertable created in Phase 11 migrations)
**Requirements**: WRCL-01, WRCL-02, WRCL-03, WRCL-04, WRCL-05, WRCL-06
**Success Criteria** (what must be TRUE):
1. Poller collects per-client registration data (MAC, signal, CCQ, TX/RX rates, distance, uptime) from APs on a 5-minute cadence
2. Poller collects per-interface RF stats (noise floor, channel width, TX power, client count) via the monitor command
3. Per-client data publishes to a dedicated WIRELESS_REGISTRATIONS NATS stream (not DEVICE_EVENTS)
4. Per-client data stores in a dedicated hypertable with 30-day retention
5. Collection works correctly on both RouterOS v6 (wireless package) and v7 (wifi package) with graceful handling of missing fields
**Plans**: TBD
Plans:
- [ ] 12-01: TBD
- [ ] 12-02: TBD
### Phase 13: Link Discovery + Registration Ingestion
**Goal**: Backend automatically discovers AP-CPE relationships from wireless registration data and maintains link state with temporal stability
**Depends on**: Phase 12 (per-client data flowing through NATS)
**Requirements**: LINK-01, LINK-02, LINK-03, LINK-04
**Success Criteria** (what must be TRUE):
1. Backend matches registration table MAC addresses against known device interface MACs to discover AP-CPE links
2. Link state follows a temporal state machine (discovered, active, degraded, down, stale) with consecutive-miss threshold to prevent false flapping
3. Discovered links are stored in a materialized wireless_links table for fast dashboard queries
4. Wireless clients whose MACs do not match any managed device appear as "unknown clients" with their signal and rate data preserved
**Plans**: TBD
Plans:
- [ ] 13-01: TBD
- [ ] 13-02: TBD
### Phase 14: Site Dashboard + Sector Views + Wireless UI
**Goal**: Operators can drill into any site to see device health, sector-organized AP/CPE views, and per-station wireless details on device pages
**Depends on**: Phase 13 (wireless_links populated, registration data queryable)
**Requirements**: DASH-02, DASH-03, DASH-04, SECT-01, SECT-02, SECT-03, WRUI-01, WRUI-02, WRUI-03
**Success Criteria** (what must be TRUE):
1. Site dashboard shows a device health grid with status, CPU, memory, and uptime for all devices at the site
2. Sector-centric view within the site dashboard groups APs by sector, showing connected CPEs, aggregate bandwidth, and signal distribution
3. Site dashboard displays wireless link topology showing which CPEs connect to which APs with signal quality indicators
4. Device detail page shows a per-station wireless table (connected clients with MAC, signal, CCQ, TX/RX rates, distance, uptime) and per-interface RF stats
5. Operator can define sectors within a site, assign APs to sectors, and view aggregate stats per sector
**Plans**: TBD
Plans:
- [ ] 14-01: TBD
- [ ] 14-02: TBD
- [ ] 14-03: TBD
### Phase 15: Signal Trending + Site Alerting
**Goal**: Operators can track signal quality over time and receive alerts when site or sector conditions degrade
**Depends on**: Phase 14 (dashboards exist to surface trends and alerts); requires accumulated wireless data from Phases 12-13
**Requirements**: TRND-01, TRND-02, ALRT-01, ALRT-02
**Success Criteria** (what must be TRUE):
1. Operator can view per-station signal history charts showing signal strength over time
2. System detects and surfaces signal degradation trends (e.g., "signal dropped 8dB over 2 weeks")
3. Operator can create site-scoped alert rules (e.g., "alert when >20% of devices at this site go offline")
4. Operator can create sector-scoped alert rules (e.g., "alert when sector average signal drops below -75dBm")
**Plans**: TBD
Plans:
- [ ] 15-01: TBD
- [ ] 15-02: TBD
## Coverage
| Category | Requirements | Phase | Count |
|----------|-------------|-------|-------|
| Sites | SITE-01, SITE-02, SITE-03, SITE-04, SITE-05, SITE-06 | 11 | 2/3 | In Progress| | DASH-01 | 11 | 1 |
| Site Dashboard | DASH-02, DASH-03, DASH-04 | 14 | 3 |
| Sectors | SECT-01, SECT-02, SECT-03 | 14 | 3 |
| Wireless Collection | WRCL-01, WRCL-02, WRCL-03, WRCL-04, WRCL-05, WRCL-06 | 12 | 6 |
| Link Discovery | LINK-01, LINK-02, LINK-03, LINK-04 | 13 | 4 |
| Wireless UI | WRUI-01, WRUI-02, WRUI-03 | 14 | 3 |
| Signal Trending | TRND-01, TRND-02 | 15 | 2 |
| Site Alerting | ALRT-01, ALRT-02 | 15 | 2 |
| **Total** | | | **30** |
## Progress
**Execution Order:**
Phases execute in numeric order: 11 -> 11.x -> 12 -> 12.x -> 13 -> 13.x -> 14 -> 14.x -> 15
| Phase | Plans Complete | Status | Completed |
|-------|----------------|--------|-----------|
| 11. Site Data Model + Foundation | 0/3 | Planning complete | - |
| 12. Per-Client Wireless Collection | 0/? | Not started | - |
| 13. Link Discovery + Registration Ingestion | 0/? | Not started | - |
| 14. Site Dashboard + Sector Views + Wireless UI | 0/? | Not started | - |
| 15. Signal Trending + Site Alerting | 0/? | Not started | - |
---
*Roadmap created: 2026-03-18*
*Last updated: 2026-03-18*

73
.planning/STATE.md Normal file
View File

@@ -0,0 +1,73 @@
---
gsd_state_version: 1.0
milestone: v9.7
milestone_name: Tower & Site Management
status: unknown
stopped_at: Completed 11-02-PLAN.md
last_updated: "2026-03-19T02:47:05Z"
progress:
total_phases: 5
completed_phases: 0
total_plans: 3
completed_plans: 2
---
# Project State
## Project Reference
See: .planning/PROJECT.md (updated 2026-03-18)
**Core value:** Operators can monitor, configure, and troubleshoot their entire MikroTik fleet from a single pane of glass
**Current focus:** Phase 11 — site-data-model-foundation
## Current Position
Phase: 11 (site-data-model-foundation) — EXECUTING
Plan: 3 of 3
## Performance Metrics
**Velocity:**
- Total plans completed: 1
- Average duration: 3 min
- Total execution time: 0.05 hours
**By Phase:**
| Phase | Plans | Total | Avg/Plan |
|-------|-------|-------|----------|
| - | - | - | - |
## Accumulated Context
| Phase 11 P01 | 3min | 2 tasks | 9 files |
| Phase 11 P02 | 6min | 3 tasks | 8 files |
### Decisions
Decisions are logged in PROJECT.md Key Decisions table.
- Sites must use nullable site_id FK (never mandatory) to preserve flat-list workflow
- Per-client wireless data gets its own NATS stream and hypertable (not DEVICE_EVENTS or wireless_metrics)
- Link state machine requires 3 consecutive missed polls before marking down (prevents false flapping)
- [Phase 11]: alert_count set to 0 with TODO -- alert_events integration deferred to avoid coupling
- [Phase 11]: Site detail page kept minimal (info + stats) -- full dashboard deferred to Phase 14
- [Phase 11]: Used Dialog for delete confirmation (no AlertDialog component in UI library)
### Pending Todos
None yet.
### Blockers/Concerns
- OpenBao dev instance loses Transit keys on data wipe — device creds need re-entry
- RouterOS 7 WiFi registration-table field names need validation on real hardware (Phase 12)
- MAC-to-device resolution data source needs codebase audit (Phase 13)
## Session Continuity
Last session: 2026-03-19T02:47:05Z
Stopped at: Completed 11-02-PLAN.md
Resume file: None

116
.planning/phases/11-site-data-model-foundation/11-02-SUMMARY.md Normal file
View File

@@ -0,0 +1,116 @@
---
phase: 11-site-data-model-foundation
plan: 02
subsystem: ui, frontend
tags: [react, tanstack-router, tanstack-query, tailwind, lucide]
# Dependency graph
requires:
- phase: 11-site-data-model-foundation plan 01
provides: Sites CRUD REST API with health rollup
provides:
- Site list page with sortable table, search, and CRUD dialogs
- Site detail page with health stats summary
- sitesApi frontend client with CRUD + device assignment methods
- Sites navigation in sidebar and tenant index
affects: [11-03, 14-site-dashboard]
# Tech tracking
tech-stack:
added: []
patterns:
- "SiteTable follows FleetTable pattern (SortHeader, EmptyState, TableSkeleton)"
- "SiteFormDialog uses useMutation with queryClient.invalidateQueries for cache sync"
- "Delete confirmation via Dialog component (no separate AlertDialog needed)"
key-files:
created:
- frontend/src/lib/api.ts (sitesApi section)
- frontend/src/components/sites/SiteFormDialog.tsx
- frontend/src/components/sites/SiteTable.tsx
- frontend/src/routes/_authenticated/tenants/$tenantId/sites/index.tsx
- frontend/src/routes/_authenticated/tenants/$tenantId/sites/$siteId.tsx
modified:
- frontend/src/components/layout/Sidebar.tsx
- frontend/src/routes/_authenticated/tenants/$tenantId/index.tsx
- frontend/src/routeTree.gen.ts
key-decisions:
- "Used Dialog component for delete confirmation instead of AlertDialog (not present in UI library)"
- "Textarea rendered as native element with project styling (no Textarea UI component exists)"
- "Site detail page is intentionally minimal -- full dashboard deferred to Phase 14"
patterns-established:
- "Sites components in frontend/src/components/sites/ directory"
- "canWrite(user) gates edit/delete actions in table rows"
requirements-completed: [DASH-01, SITE-01, SITE-02]
# Metrics
duration: 6min
completed: 2026-03-19
---
# Phase 11 Plan 02: Frontend Site List and Detail Pages Summary
**Site list page with sortable table, health rollup columns, CRUD dialogs, delete confirmation, and site detail page with stats cards**
## Performance
- **Duration:** 6 min
- **Started:** 2026-03-19T02:41:33Z
- **Completed:** 2026-03-19T02:47:05Z
- **Tasks:** 3
- **Files modified:** 8
## Accomplishments
- sitesApi client with all CRUD methods plus assignDevice, removeDevice, and bulkAssign
- Site list page at /tenants/{tenantId}/sites with sortable table, search filter, create/edit dialogs, and delete confirmation
- Site detail page at /tenants/{tenantId}/sites/{siteId} with info card and health stats (devices, online, online %, alerts)
- Sites navigation integrated into sidebar Fleet section and tenant index page with count card
## Task Commits
Each task was committed atomically:
1. **Task 1: Add sitesApi client and SiteFormDialog component** - `3a965e0` (feat)
2. **Task 2: Create SiteTable, site list page, and site detail page** - `40f2bcd` (feat)
3. **Task 3: Add Sites to sidebar navigation and tenant index page** - `e8c69fb` (feat)
## Files Created/Modified
- `frontend/src/lib/api.ts` - Added SiteResponse, SiteListResponse, SiteCreate, SiteUpdate interfaces and sitesApi client
- `frontend/src/components/sites/SiteFormDialog.tsx` - Create/edit site dialog with mutation and cache invalidation
- `frontend/src/components/sites/SiteTable.tsx` - Sortable table with delete confirmation, unassigned row, empty state
- `frontend/src/routes/_authenticated/tenants/$tenantId/sites/index.tsx` - Site list page route
- `frontend/src/routes/_authenticated/tenants/$tenantId/sites/$siteId.tsx` - Site detail page with health stats
- `frontend/src/components/layout/Sidebar.tsx` - Added MapPin icon and Sites nav link
- `frontend/src/routes/_authenticated/tenants/$tenantId/index.tsx` - Added Sites count card and "Manage sites" link
- `frontend/src/routeTree.gen.ts` - Regenerated with new site routes
## Decisions Made
- Used Dialog component for delete confirmation instead of AlertDialog (AlertDialog not present in the project UI library)
- Used native textarea element with project Tailwind styling since no Textarea UI component exists
- Site detail page kept intentionally minimal (info + stats) -- full site dashboard with device list deferred to Phase 14
## Deviations from Plan
None - plan executed exactly as written.
## Issues Encountered
- Route tree (routeTree.gen.ts) needed regeneration via vite build to register new site routes -- resolved by running `npx vite build`
## User Setup Required
None - no external service configuration required.
## Next Phase Readiness
- Site list and detail pages ready for map integration (Plan 03)
- Site detail page ready for Phase 14 full dashboard expansion (device list, map, sector views)
- Frontend can connect to backend sites API once backend migration 030 is run
## Self-Check: PASSED
All created files verified on disk. All 3 task commits (3a965e0, 40f2bcd, e8c69fb) verified in git log.
---
*Phase: 11-site-data-model-foundation*
*Completed: 2026-03-19*