From b85d81c2e858611e94ad0d329109fca0511416b1 Mon Sep 17 00:00:00 2001
From: admin <cloud@tck.com.my>
Date: Fri, 13 Mar 2026 06:19:04 +0800
Subject: [PATCH] docs: add Phase 1 context

---
 .planning/01-CONTEXT.md | 104 ++++++++++++++++++++++++++++++++++++++++
 1 file changed, 104 insertions(+)
 create mode 100644 .planning/01-CONTEXT.md

diff --git a/.planning/01-CONTEXT.md b/.planning/01-CONTEXT.md
new file mode 100644
index 000000000..404f0892c
--- /dev/null
+++ b/.planning/01-CONTEXT.md
@@ -0,0 +1,104 @@
+# 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*