# 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.*