sp80/.planning/research/SUMMARY.md

# Project Research Summary

**Project:** TCKRTUIYO - RTU Web Interface
**Domain:** Embedded IoT/SCADA Web Interface for Rainfall Monitoring
**Researched:** 2026-03-13
**Confidence:** HIGH

## Executive Summary

This research covers the development of a web-based interface for a Remote Terminal Unit (RTU) used in rainfall monitoring, deployed on Raspberry Pi Zero 2 W hardware with constrained resources (1GHz quad-core, 512MB RAM). Based on comprehensive research across technology stacks, feature requirements, architecture patterns, and common pitfalls, the recommended approach is a React 19 + Vite 8 + Tailwind 4 stack, optimized for embedded kiosk deployment with aggressive performance budgets.

The RTU interface must serve dual purposes: a touch-optimized local dashboard on a 7" 1024x600 touchscreen display, and a responsive remote interface for desktop users. Experts in this domain emphasize hardware-aware development—the Pi Zero 2 W's limited resources demand strict bundle size budgets (<170KB initial JS), memory-bounded data handling (circular buffers, not unbounded state growth), and careful avoidance of performance anti-patterns that work fine on development machines but cripple embedded deployments. The architecture should follow a clean separation between presentation, state management, and hardware interface layers, with a Python backend handling GPIO/ADC operations and a React frontend communicating via REST API.

Critical risks include memory leaks from improper cleanup (fatal for 24/7 operation), layout thrashing from unoptimized re-renders, and kiosk-specific UX failures from designing for mouse rather than touch. These are all preventable with the right patterns: React.memo for dashboard components, proper useEffect cleanup, minimum 44px touch targets, and aggressive testing on actual Pi hardware throughout development—not just at the end.

## Key Findings

### Recommended Stack

For a production RTU interface on Pi Zero 2 W constraints, the stack prioritizes bundle size reduction and runtime performance while maintaining developer ergonomics. React 19 (not Preact) is recommended because shadcn/ui component library requires React ecosystem compatibility. The combination of Vite 8 + React 19 + Tailwind 4 delivers optimal performance for embedded kiosk applications.

**Core technologies:**
- **React 19.2.4**: UI rendering — 15-20% smaller than React 18, required for shadcn/ui compatibility, supports Concurrent Features for better performance
- **Vite 8.0.0**: Build tool — Fastest HMR, superior tree-shaking vs webpack, Rollup-based production builds optimized for embedded targets
- **Tailwind CSS 4.2.0**: Styling — Zero-runtime CSS with CSS variables + Vite plugin, ~3KB CSS for typical component set vs 100KB+ traditional CSS
- **shadcn/ui**: Component library — Headless UI components copy-pasted into repo (tree-shakeable), Radix UI primitives underneath
- **React Router 7.x**: Routing — Type-safe routing, data APIs, smaller than v6, non-breaking from v6
- **Zustand 5.0.11**: State management — ~1.1KB bundle, minimal boilerplate, no providers needed, excellent TypeScript support

**Bundle size budget:** <200KB total JS gzipped for initial load (leaves 30KB buffer for application code)

**Performance optimizations required:**
- Aggressive code splitting with manual chunks for react-vendor and router-vendor
- Drop console.* and debugger in production builds
- React.memo for dashboard components
- Debounce sensor data updates to 100-200ms
- Use CSS transforms instead of layout properties for animations

**What NOT to use:**
- Preact (incompatible with shadcn/ui despite smaller size)
- Redux Toolkit (15KB+ overhead vs Zustand's 1KB)
- TanStack Query (12KB+ for simple polling—use native fetch + Zustand instead)
- Material UI / Ant Design (100KB+ CSS-in-JS runtime)
- Create React App (deprecated, poor tree-shaking)
- Emotion / Styled Components (CSS-in-JS runtime overhead)

### Expected Features

Based on analysis of existing RTU interfaces, IoT dashboard patterns, and project requirements.

**Must have (table stakes):**
- Real-time rainfall display (Today, Hourly, Monthly Acc, Yearly Acc) — core purpose of RTU, must update without page refresh
- Solar/Battery voltage monitoring — critical for field maintenance scheduling, color-coded warnings for low voltage
- Station identification (ID, coordinates, serial number) — multiple stations in field, visible on all screens
- Date/time display with sync status — large, readable format, essential for data timestamping
- Communication status (GPRS/Network) — remote stations need connectivity visibility, last sync timestamp
- Historical data viewing (24h time-series charts) — essential for hydrology analysis
- Device configuration (4 key categories: Rainfall, ADC, Network, GPRS) — field calibration necessary
- Data export (CSV download) — external analysis required for hydrology software integration
- Alarm indicators — visual/audible alerts for high rainfall, low battery, communication loss

**Should have (competitive):**
- Touch-optimized 7" UI (44px+ touch targets, finger-friendly) — most competitors use desktop-oriented interfaces
- Dual-mode display (1024x600 kiosk + Full HD remote) — single codebase serves both use cases
- Sub-1-second refresh — near real-time monitoring for critical events via WebSocket or SSE
- Extended time ranges (7d, 30d, 1y charts) — longer historical views for trend analysis
- Alarm threshold configuration — custom alerts for site-specific conditions
- Full settings suite (remaining 7 categories: Utility, Calibration, Flash, Mobile, EVAP, Level, Siren)
- One-touch calibration — guided wizard vs manual parameter entry

**Defer (v2+):**
- Offline data buffering with sync — adds significant complexity, cloud-only solutions handle this
- Multi-station dashboard — single-station focus for MVP
- Advanced analytics (rainfall intensity, accumulation rates) — complex, niche use cases
- Network protocol options (FTP/SCP/SFTP/WebDAV) — customer infrastructure requirements can wait
- Remote configuration API — third-party integration needs customer demand validation

**Anti-features to avoid:**
- Mobile app (responsive web works on all devices, no installation overhead)
- Cloud data storage (adds cost, connectivity dependency, latency, security concerns)
- Real-time 3D visualizations (heavy on Pi Zero resources, adds no analytical value)
- Multi-touch gestures (error-prone with gloved hands, outdoor use)
- Voice control (unreliable in outdoor/industrial noise)
- Predictive analytics/AI (overkill for rainfall monitoring)

### Architecture Approach

Modern RTU web interfaces bridge physical sensors with human operators. The architecture balances real-time data visualization, configuration management, and remote accessibility while operating on constrained hardware. A layered architecture provides clear separation of concerns and enables testing at each level.

**Major components:**
1. **Presentation Layer** — Dashboard UI, Settings UI (11 submenus), Calibration UI, Navigation/Router. Dashboard optimized for 1024x600, refresh every 1-5s.
2. **State Management Layer** — Sensor Data Store (rainfall, voltage, ADC, status), Configuration Store (settings, calibration, network), UI Store (theme, layout mode). Uses Zustand for minimal overhead.
3. **Data Access Layer** — Sensor API (real-time), Config API (CRUD), File Manager (CSV/Flash), Network API (FTP/SCP). Abstracts hardware communication via RESTful interface.
4. **Hardware Interface Layer** — Rainfall sensor, ADC inputs (4-20mA), GPIO/Power monitoring, Network interface. Python backend handles GPIO access, serial communication, ADC reading.

**Key patterns to follow:**
- **Dual-Mode Display Architecture**: Single codebase supporting kiosk mode (1024x600, touch-optimized) and remote mode (Full HD, desktop-friendly). Detection via viewport or port (8080=kiosk, 9090=remote).
- **Polling-Based Real-Time Updates**: Periodic data fetching (1-5s interval) with optimistic UI updates. Use when WebSocket is unavailable or too resource-intensive for embedded hardware.
- **Offline-First Configuration**: Configuration changes persisted locally first (localStorage), synced to backend asynchronously. Critical for intermittent network connectivity.

**Project structure:**
- `components/ui/` — shadcn/ui base components (copy-paste ready)
- `components/dashboard/` — Dashboard-specific components optimized for 7" display
- `components/settings/` — Modular settings forms, one per configuration category
- `hooks/` — Custom React hooks for data fetching and hardware interaction
- `stores/` — Zustand stores for sensor data, configuration, UI state
- `services/` — API abstraction layer for hardware communication
- `views/` — Page-level components corresponding to routes (Dashboard, Settings/*, Calibration, FlashMemory)

**Anti-patterns to avoid:**
- Heavy frameworks on embedded (Next.js, Redux) — Pi Zero has limited RAM
- Real-time everything (constant polling) — drains battery, saturates network
- Tight hardware coupling (direct GPIO access from JavaScript) — security risk, platform lock-in
- Ignoring kiosk constraints (designing for desktop) — 1024x600 is cramped, no right-click menus

### Critical Pitfalls

Research identified 8 critical pitfalls specific to RTU interfaces on Raspberry Pi, all preventable with the right patterns and testing.

1. **Ignoring Hardware Performance Constraints** — Developers build on powerful machines, deploy to Pi Zero where code runs at 2-5 FPS. *Avoid:* Set hard budgets (<170KB JS, <2s LCP), test on actual hardware weekly, use Chrome DevTools Performance throttling (6x CPU slowdown approximates Pi Zero).

2. **Unbounded Real-Time Data Accumulation** — Dashboard polls every 1-5 seconds, stores all data in React state. After 24-48 hours, browser crashes from memory pressure. *Avoid:* Implement circular buffers (keep only last N points, e.g., 1000 points = ~20 minutes), store historical data in SQLite/file system, add `document.visibility` check to pause polling when tab hidden.

3. **Layout Thrashing from Unoptimized Re-renders** — Sensor updates trigger React re-renders of entire tree, causing forced reflow. On Pi Zero, creates jank/jerky animations. *Avoid:* Memoize components with `React.memo`, use `useMemo` for expensive calculations, colocate state (not global), use CSS transforms instead of layout properties, debounce visual updates to 30fps max.

4. **Blocking Main Thread with Synchronous Operations** — CSV file operations, data serialization run on main thread. During 100-500ms operations, UI becomes completely unresponsive. *Avoid:* Use Web Workers for all CSV processing, yield to main thread with `setTimeout(..., 0)`, stream CSV data instead of loading entire file, use `performance.mark()` to identify long tasks (>50ms).

5. **Kiosk Mode UI Anti-Patterns** — Dashboard designed for mouse/keyboard deployed to 7" touchscreen. Buttons too small, hover states don't work, users get trapped in deep settings. *Avoid:* Minimum 48x48px touch targets (Apple HIG) or 44x44px (Material Design), use `:active` not just `:hover`, always show back button in settings sub-pages, test with actual fingers on target display size.

6. **Not Handling Browser Resource Throttling** — Dashboard works during active use, but when idle for hours, Chromium throttles timers. Real-time sensor data stops updating. *Avoid:* Implement Page Visibility API to adjust behavior when `document.hidden`, use Web Workers for background processing (not throttled), add visual indicator showing "live" vs "stale" data.

7. **Memory Leaks from Event Listeners and Subscriptions** — Component mounts add listeners/WebSockets, unmounts don't clean up. Memory grows with each navigation cycle. *Avoid:* Always return cleanup function from useEffect, use `AbortController` for fetch cancellation, remove all addEventListener with matching removeEventListener, use React StrictMode during development (double-mounts expose leaks).

8. **Choking the Pixel Pipeline with Expensive CSS** — Heavy effects (box-shadow, backdrop-filter) trigger expensive paint/composite operations. On Pi Zero's GPU, results in dropped frames. *Avoid:* Prefer `transform` and `opacity` for animations, avoid `backdrop-filter` entirely on Pi Zero (software fallback), use Chrome DevTools Layers panel to diagnose layer count, limit simultaneous animations to 2-3 elements.

**"Looks Done But Isn't" checklist:**
- [ ] Dashboard loads: Tested on actual Pi Zero 2 W hardware, not just dev machine
- [ ] Memory bounded: Running for 24+ hours without memory growth
- [ ] Touch optimized: All interactions tested with finger on 7" touchscreen
- [ ] Kiosk configured: Chromium flags set for kiosk mode
- [ ] Performance budget met: <170KB initial JS, <2s LCP on target hardware
- [ ] No layout thrashing: Chrome DevTools Performance shows minimal purple (layout) bars
- [ ] Visibility aware: Page handles backgrounding/throttling correctly
- [ ] Cleanup implemented: All useEffect hooks have proper cleanup functions

## Implications for Roadmap

Based on combined research, the following phase structure is recommended to build the RTU interface while avoiding critical pitfalls:

### Phase 1: Foundation & MVP Dashboard
**Rationale:** Core dependencies and infrastructure must be established first. Dashboard is the primary user-facing feature and has the most stringent performance requirements. Addressing performance pitfalls early prevents costly rework.

**Delivers:**
- Project setup with Vite 8, React 19, TypeScript, Tailwind 4, shadcn/ui
- Basic routing and layout structure
- Sensor data API integration layer
- Dashboard with real-time rainfall display, voltage monitoring, station info header
- 24-hour historical chart
- Performance budget validated on Pi Zero 2 W hardware

**Uses:** React 19, Vite 8, Tailwind 4, shadcn/ui, React Router 7, Zustand

**Addresses (from FEATURES.md):** Real-time rainfall display, solar/battery monitoring, station info header, 24-hour historical chart

**Avoids (from PITFALLS.md):** Hardware performance constraints, layout thrashing, kiosk mode UI anti-patterns, memory leaks, expensive CSS

**Research flag:** Standard patterns—no additional research needed. Use established React/Vite patterns.

### Phase 2: Data Persistence & Settings Framework
**Rationale:** Settings infrastructure is required before implementing individual settings categories. Data persistence layer must handle bounded memory from day one (circular buffers). Builds on dashboard's sensor data layer.

**Delivers:**
- Settings navigation and layout framework
- Form components with validation
- Configuration store (Zustand) with localStorage persistence
- Offline-first configuration pattern
- Basic settings: Station Info, Date/Time, Network Setup
- Data retention policies and circular buffer implementation

**Uses:** Zustand stores, localStorage/IndexedDB, form validation utilities

**Addresses (from FEATURES.md):** Key settings categories (4), basic device configuration

**Avoids (from PITFALLS.md):** Unbounded data accumulation, memory leaks, offline resilience gaps

**Research flag:** Standard patterns—configuration management is well-documented. Test circular buffer implementation on Pi hardware.

### Phase 3: Extended Settings & CSV Workflow
**Rationale:** Complete the settings suite with remaining categories. CSV export is a medium-complexity feature requiring file operations that must not block the main thread.

**Delivers:**
- Remaining settings categories: ADC, Rainfall, GPRS, Utility, Calibration, Flash, Mobile, EVAP, Level, Siren
- CSV data export functionality
- File manager view (Flash/USB)
- Web Workers for CSV processing
- Progress indicators for async operations

**Uses:** Web Workers, FileReader API, CSV parsing libraries

**Addresses (from FEATURES.md):** Full settings suite, CSV data export, data export

**Avoids (from PITFALLS.md):** Blocking main thread with synchronous operations, memory leaks from file operations

**Research flag:** May need research on CSV libraries compatible with Web Workers and Pi Zero constraints.

### Phase 4: Network Stack & Remote Access
**Rationale:** Network protocols and remote access features are complex and can be deferred until core functionality is stable. Requires careful handling of browser throttling for long-running connections.

**Delivers:**
- Network protocol options (FTP/SCP/SFTP/WebDAV) for data push
- Dual-mode display implementation (kiosk vs remote detection)
- Page Visibility API implementation for background handling
- Network status detection and offline indicators
- Remote server integration (HTTP POST / MQTT for data transmission)

**Uses:** Background services, HTTP clients, MQTT if applicable

**Addresses (from FEATURES.md):** Dual-mode display, network protocol options

**Avoids (from PITFALLS.md):** Browser resource throttling, network status detection mistakes

**Research flag:** May need research on specific protocol implementations (FTP/SCP/SFTP/WebDAV) for embedded Linux.

### Phase 5: Advanced Features & Polish
**Rationale:** Alarm system and calibration wizard add significant value but are not required for core functionality. Can be added once MVP is stable and validated.

**Delivers:**
- Alarm threshold configuration
- Visual/audible alarm indicators
- Calibration wizard (ADC channel calibration, level sensor calibration)
- Extended time ranges (7d, 30d, 1y charts)
- Touch optimization refinements
- Performance tuning based on field feedback

**Uses:** Threshold logic, wizard pattern, chart extensions

**Addresses (from FEATURES.md):** Alarm thresholds, calibration wizard, extended time ranges, touch optimization

**Avoids (from PITFALLS.md):** Memory leaks from alarm subscriptions, layout thrashing from chart updates

**Research flag:** Standard patterns—wizard and threshold logic are well-established.

### Phase Ordering Rationale

1. **Dashboard First:** The dashboard is the core value proposition and has the strictest performance requirements. Validating performance on Pi hardware early prevents costly architectural changes later.

2. **Settings Framework Before Individual Settings:** The settings navigation and form infrastructure is a prerequisite for all 11 settings categories. Building the framework first enables parallel development of individual settings.

3. **CSV Before Network Protocols:** CSV export is simpler and shares file handling logic with the network stack. Mastering file operations in CSV phase informs the more complex network protocol implementations.

4. **Remote Access Last:** Network protocols and dual-mode display are valuable but not required for core RTU functionality. They add complexity (background services, protocol handling) that can be deferred.

5. **Pitfall Avoidance Throughout:** Each phase explicitly addresses specific pitfalls from research. Performance testing in Phase 1, bounded memory in Phase 2, non-blocking operations in Phase 3, throttling handling in Phase 4.

### Research Flags

Phases likely needing deeper research during planning:
- **Phase 3 (CSV Workflow):** Specific CSV libraries compatible with Web Workers and Pi Zero memory constraints. Streaming CSV parsing vs loading entire file.
- **Phase 4 (Network Stack):** FTP/SCP/SFTP/WebDAV implementation options for embedded Linux. Python libraries vs shell commands. Security implications of each protocol.

Phases with standard patterns (skip research-phase):
- **Phase 1 (MVP Dashboard):** Well-established React/Vite/shadcn/ui patterns. Performance optimization strategies are documented.
- **Phase 2 (Settings Framework):** Form handling and state management are standard React patterns. Zustand usage is well-documented.
- **Phase 5 (Advanced Features):** Wizard and threshold logic are standard UI patterns. No domain-specific research needed.

## Confidence Assessment

| Area | Confidence | Notes |
|------|------------|-------|
| Stack | HIGH | All technologies verified with official sources (React 19.2.4, Vite 8.0.0, Tailwind 4.2.0, React Router 7, Zustand 5.0.11). Bundle size claims verified via bundlephobia. |
| Features | HIGH | Based on analysis of existing codebase (16 view components), ThingsBoard and Grafana dashboard patterns, industrial HMI design principles, and project requirements from PROJECT.md. |
| Architecture | HIGH | Patterns drawn from React/Vite documentation, shadcn/ui architecture, SCADA system patterns, and existing codebase structure. Layered architecture is standard for embedded systems. |
| Pitfalls | HIGH | Sources include web.dev performance docs (Google), MDN Web Performance, React documentation, and Chromium kiosk mode behavior. Hardware specs verified. |

**Overall confidence:** HIGH

All research areas have high confidence due to multiple authoritative sources and verification of specific versions. The stack recommendations are current as of research date (March 2026). The embedded/IoT domain has well-established patterns for constrained hardware deployment.

### Gaps to Address

- **Hardware API Specification:** Research assumes REST API to Python backend, but specific endpoint contracts and data formats need definition during requirements phase. Coordinate with Python backend team.

- **CSV Library Selection:** Specific library for CSV processing (Papa Parse, d3-dsv, custom) needs evaluation during Phase 3 planning. Must support Web Workers and streaming for Pi Zero constraints.

- **Network Protocol Prioritization:** Order of implementing FTP/SCP/SFTP/WebDAV should be determined by customer requirements. Not all may be needed for MVP.

- **Touchscreen Hardware Details:** Exact touchscreen specifications (resistive vs capacitive, bezel size) may affect touch target sizing recommendations. Validate 44px minimum on actual hardware.

- **Chromium Version on Target OS:** Kiosk mode flags and throttling behavior may vary by Chromium version on Raspberry Pi OS. Verify during Phase 1 testing on actual hardware.

- **Backup/Recovery Strategy:** Research focused on runtime behavior. Backup/recovery of configuration and data needs definition during architecture phase.

## Sources

### Primary (HIGH confidence)
- React 19 Documentation (react.dev) — React 19 features, Concurrent Features, bundle size
- React GitHub Releases (v19.2.4, Jan 26 2026) — Version verification
- Vite Documentation (vitejs.dev) — Vite 8.0.0 configuration, build optimization
- Tailwind CSS Documentation (tailwindcss.com) — Tailwind 4.2.0 installation with Vite, zero-runtime CSS
- React Router Documentation (reactrouter.com) — React Router 7 features, migration from v6
- Zustand GitHub Releases (v5.0.11, Feb 2026) — State management patterns
- web.dev Performance Budgets 101 — Bundle size guidelines
- web.dev Optimize LCP/INP — Performance metrics
- MDN Page Visibility API — Background tab handling
- Raspberry Pi Zero 2 W Specifications — Hardware constraints (1GHz quad-core, 512MB RAM)

### Secondary (MEDIUM confidence)
- shadcn/ui Documentation — Component library patterns (no semantic versioning, tracks Radix releases)
- ThingsBoard IoT Dashboard Documentation — Dashboard patterns for IoT devices
- Grafana Dashboard Best Practices — Time-series visualization patterns
- Inductive Automation HMI Resources — Industrial HMI design principles
- Chromium Kiosk Mode documentation — Resource throttling behavior (some variation by version)
- Industrial touchscreen UX research — 44px minimum touch targets, no hover states

### Tertiary (LOW confidence)
- Existing codebase analysis (16 view components) — Domain-specific requirements validation
- Project requirements from PROJECT.md — Validated requirements and constraints

---
*Research completed: 2026-03-13*
*Ready for roadmap: yes*