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