177 lines
5.4 KiB
Markdown
177 lines
5.4 KiB
Markdown
# Phase 1: Foundation & Dashboard - Research
|
|
|
|
**Phase:** 1
|
|
**Researched:** 2026-03-13
|
|
**Confidence:** HIGH
|
|
|
|
---
|
|
|
|
## Research Question
|
|
|
|
What do we need to know to PLAN Phase 1 well? Phase 1 delivers a modern, performant dashboard for rainfall monitoring on Raspberry Pi Zero 2 W hardware.
|
|
|
|
---
|
|
|
|
## Key Findings
|
|
|
|
### Dashboard Requirements (from CONTEXT.md + ROADMAP)
|
|
|
|
**Must Display:**
|
|
1. Real-time rainfall data (Today, Hourly, MAR Acc, Yearly Acc) — DASH-01
|
|
2. Solar voltage reading — DASH-02
|
|
3. Battery voltage with HIGH/LOW status indicator — DASH-03
|
|
4. Station ID and version info — DASH-04
|
|
5. Real-time clock (HH:MM:SS) and date (YYYY-MM-DD) — DASH-05
|
|
6. Communication status (ASU/dBm/percentage) — DASH-06
|
|
7. Login status indicator — DASH-07
|
|
|
|
**UI Requirements:**
|
|
- Modern, compact design optimized for 1024x600 — UI-01
|
|
- Touch-friendly (44px+ touch targets) — UI-02
|
|
- Responsive layout for Full HD remote access — UI-03
|
|
- <200KB JS bundle for Pi Zero 2 W — UI-04
|
|
- Navigation menu to Settings, Calibration, Flash Memory — UI-05
|
|
|
|
### Implementation Decisions (Locked)
|
|
|
|
**Layout:**
|
|
- 3-panel layout: Sidebar | Header + Content
|
|
- Header contains: Logo, Time, Date, Station ID, Comm Status, Version, Login Status, Solar Voltage, Battery Voltage
|
|
- Rainfall cards in grid with color-coding
|
|
|
|
**Dual-Mode Display:**
|
|
- Port 8080 = Kiosk mode (1024x600)
|
|
- Port 9090 = Full HD remote mode
|
|
- Detection via `window.location.port`
|
|
|
|
**State Management:**
|
|
- Zustand (~1.1KB) for sensor data
|
|
- localStorage + backend sync for settings persistence
|
|
- Offline-first architecture
|
|
|
|
**Real-time Data:**
|
|
- Polling-based (default 5s, user adjustable)
|
|
- API client with mock fallback for demo/offline
|
|
|
|
### Technology Stack (from existing research)
|
|
|
|
**Confirmed Stack:**
|
|
- React 19.2.4 — 15-20% smaller than v18, required for shadcn/ui
|
|
- Vite 8.0.0 — Fast HMR, superior tree-shaking
|
|
- Tailwind CSS 4.2.0 — Zero-runtime CSS
|
|
- React Router 7.x — Type-safe routing
|
|
- Zustand 5.0.11 — ~1.1KB state management
|
|
- shadcn/ui — Tree-shakeable components
|
|
|
|
**Bundle Budget:** <170KB initial JS (200KB limit with buffer)
|
|
|
|
### Critical Pitfalls to Avoid
|
|
|
|
1. **Performance constraints** — Pi Zero 2 W has 1GHz quad-core, 512MB RAM
|
|
2. **Layout thrashing** — Use React.memo, debounce updates
|
|
3. **Unbounded data** — Circular buffers for historical data
|
|
4. **Kiosk anti-patterns** — 44px+ touch targets, no hover-only states
|
|
5. **Memory leaks** — Proper useEffect cleanup
|
|
6. **Blocking operations** — Keep CSV/network for Phase 3
|
|
|
|
### File Structure (from existing codebase)
|
|
|
|
**Routes:**
|
|
- `/` — Dashboard (RainfallView)
|
|
- `/utility/*` — Settings
|
|
- `/calibration` — Calibration
|
|
- `/flash-memory` — Flash Memory
|
|
|
|
**Components to Create/Modify:**
|
|
- `App.tsx` — Add mode detection
|
|
- `Header.tsx` — Modernize with all status info
|
|
- `RainfallView.tsx` — Main dashboard view
|
|
- `stores/sensorStore.ts` — New Zustand store
|
|
- `api/client.ts` — API client with mock fallback
|
|
|
|
### Dependencies to Add
|
|
|
|
- `zustand` — State management
|
|
|
|
---
|
|
|
|
## Validation Architecture
|
|
|
|
### Testable Behaviors
|
|
|
|
1. **Dashboard displays all required data fields**
|
|
- Rainfall metrics (Today, Hourly, MAR, Yearly)
|
|
- Voltage readings (Solar, Battery with status)
|
|
- Station info (ID, Version)
|
|
- Time/Date display
|
|
- Communication status
|
|
- Login indicator
|
|
|
|
2. **Touch targets meet minimum size**
|
|
- All interactive elements ≥44px
|
|
- Preferably 56px for primary actions
|
|
|
|
3. **Dual-mode display works**
|
|
- Port 8080 renders kiosk layout
|
|
- Port 9090 renders expanded layout
|
|
|
|
4. **Performance budget met**
|
|
- Initial JS <170KB gzipped
|
|
- LCP <2s on Pi Zero 2 W
|
|
|
|
5. **Data updates in real-time**
|
|
- Polling interval configurable
|
|
- Updates visible without refresh
|
|
|
|
6. **Navigation accessible**
|
|
- Sidebar shows Settings, Calibration, Flash Memory links
|
|
- Touch-friendly navigation
|
|
|
|
### Observable Outputs
|
|
|
|
| Artifact | Location | Verification |
|
|
|----------|----------|--------------|
|
|
| Dashboard component | `src/app/components/views/RainfallView.tsx` | Renders all 7 data fields |
|
|
| Header component | `src/app/components/Header.tsx` | Shows status indicators |
|
|
| Sensor store | `src/app/stores/sensorStore.ts` | Zustand store with mock data |
|
|
| API client | `src/app/api/client.ts` | Fetch with fallback |
|
|
| Mode detection | `src/app/App.tsx` | Port-based routing |
|
|
| Bundle size | Build output | <170KB initial JS |
|
|
|
|
### Key Connections
|
|
|
|
- Sensor store → Dashboard view (data flow)
|
|
- API client → Sensor store (update trigger)
|
|
- Mode detection → Layout components (responsive behavior)
|
|
- Header → Sensor store (status indicators)
|
|
|
|
---
|
|
|
|
## Standard Stack Recommendations
|
|
|
|
### What to Use
|
|
- React 19 + Vite 8 + Tailwind 4 (established)
|
|
- Zustand for state (research-validated)
|
|
- React Router 7 for navigation
|
|
- shadcn/ui Card, Badge, Separator components
|
|
- Lucide React for icons
|
|
|
|
### What NOT to Use
|
|
- Redux Toolkit (too heavy)
|
|
- TanStack Query (overkill for polling)
|
|
- Material UI (large CSS-in-JS)
|
|
- Real-time libraries (WebSocket/SSE not needed for 5s polling)
|
|
|
|
---
|
|
|
|
## Gaps Requiring Decisions
|
|
|
|
1. **API endpoint contracts** — Coordinate with Python backend team for exact data format
|
|
2. **Color scheme for status indicators** — Use existing TCK brand colors?
|
|
3. **Historical chart implementation** — Recharts is already in dependencies
|
|
4. **Polling interval bounds** — Min/max acceptable values?
|
|
|
|
---
|
|
|
|
*Research synthesis for Phase 1 planning. Based on project CONTEXT.md, ROADMAP.md, and existing codebase research.*
|