sp80/.planning/01-CONTEXT.md

Phase 1 Context - Foundation & Dashboard

Phase: 1
Created: 2026-03-13

---

Decisions Made

Dashboard Layout

• Layout: Keep current 3-panel layout (Sidebar | Header + Content)
• Header content: All in header - Logo, Time, Date, Station ID, Comm Status, Version, Login Status, Solar Voltage, Battery Voltage
• Logo: Use TCK logo from /logo/ directory
• Rainfall cards: Grid layout with color-coded cards (Today/Hourly/MAR/Yearly)

Real-time Data Strategy

• Approach: Real API with mock fallback
• Polling interval: User adjustable (stored in settings)
• Default polling: 5 seconds
• Implementation: Create API client with mock data fallback for demo/offline

Dual-Mode Display

• Detection: By port number
  • Port 8080 → Kiosk mode (1024x600)
  • Port 9090 → Full HD remote mode
• Implementation: window.location.port detection in app root
• Remote mode: Expanded dashboard with larger fonts and more information visible

State Management

• Library: Zustand (~1.1KB, research-recommended)
• Sensor data: Global state in Zustand store
• Settings persistence: localStorage + sync to backend when online
• Architecture: Offline-first - settings persist locally, sync in background

---

Code Context

Existing Assets

Routes (sample_interface/src/app/routes.ts):

• Dashboard at / (RainfallView)
• Settings under /utility/*
• Calibration at /calibration
• Flash Memory at /flash-memory

Components:

• DashboardLayout.tsx - Main layout wrapper
• Header.tsx - Header component (needs modernization)
• Sidebar.tsx - Navigation sidebar
• UI components in components/ui/ - shadcn/ui components available

Guidelines: sample_interface/guidelines/Guidelines.md - Full UI specification

Key Files to Modify

• src/app/App.tsx - Add mode detection (port-based)
• src/app/components/Header.tsx - Modernize for Phase 1
• src/app/components/views/RainfallView.tsx - Main dashboard view
• New: src/app/stores/sensorStore.ts - Zustand store for sensor data
• New: src/app/api/client.ts - API client with mock fallback

Dependencies to Add

• zustand - State management (research recommended)

---

Prior Decisions (from PROJECT.md)

• React/TypeScript stack
• shadcn/ui components
• Tailwind CSS
• Two-port architecture (8080/9090)
• <200KB bundle target for Pi Zero 2 W

---

Success Criteria

1. User sees real-time rainfall data (Today, Hourly, MAR Acc, Yearly Acc) updating automatically
2. User sees solar and battery voltage with visual status indicators
3. User sees station ID, version info, current time/date, and communication status
4. User sees login status indicator on dashboard
5. Dashboard loads in <2 seconds on Pi Zero 2 W
6. All touch targets are minimum 44px (preferably 56px)
7. Dashboard displays correctly in both 1024x600 (kiosk) and Full HD (remote) modes
8. Navigation menu provides access to Settings, Calibration, and Flash Memory sections

---

Out of Scope

• CSV processing (Phase 3)
• Network stack implementation (Phase 3)
• Full settings implementation (Phase 2)

---

Context for Phase 1 planning - decisions that guide research and planning