sp80/.planning/phases/01-foundation-dashboard/01-RESEARCH.md

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.