commit afe1603bbeea90047591ed79dcc0035c4a66f523 Author: admin Date: Fri Mar 13 01:08:16 2026 +0800 Add codebase mapping documents diff --git a/.planning/codebase/ARCHITECTURE.md b/.planning/codebase/ARCHITECTURE.md new file mode 100644 index 000000000..e03fa40b4 --- /dev/null +++ b/.planning/codebase/ARCHITECTURE.md @@ -0,0 +1,129 @@ +# Architecture + +**Analysis Date:** 2025-03-13 + +## Pattern Overview + +**Overall:** Component-based SPA with centralized routing + +**Key Characteristics:** +- Single-page application using React Router v7 +- View-based architecture where each view is a self-contained component +- Centralized navigation with collapsible sidebar +- Dark-first theme designed for industrial touch displays +- No state management library (local state only) +- UI components from shadcn/ui pattern with Radix primitives + +## Layers + +**Application Layer:** +- Purpose: Entry point and routing configuration +- Location: `sample_interface/src/app/` +- Contains: App.tsx, routes.ts +- Depends on: Components layer, Views layer +- Used by: Vite build system + +**Layout Layer:** +- Purpose: Shell components providing page structure +- Location: `sample_interface/src/app/components/` +- Contains: DashboardLayout.tsx, Sidebar.tsx, Header.tsx, NavigationButtons.tsx +- Depends on: UI component layer +- Used by: React Router + +**Views Layer:** +- Purpose: Page-level components representing routes +- Location: `sample_interface/src/app/components/views/` +- Contains: RainfallView.tsx, GraphView.tsx, ADCSettingView.tsx, LoginView.tsx, etc. +- Depends on: UI component layer +- Used by: React Router via routes.ts + +**UI Component Layer:** +- Purpose: Reusable primitive and composite components +- Location: `sample_interface/src/app/components/ui/` +- Contains: button.tsx, card.tsx, input.tsx, sidebar.tsx (shadcn), ~40+ components +- Depends on: Radix UI primitives, Tailwind CSS +- Used by: Views, Layouts, other UI components + +**Style Layer:** +- Purpose: Global styles and design tokens +- Location: `sample_interface/src/styles/` +- Contains: index.css, tailwind.css, theme.css +- Depends on: Tailwind CSS v4 +- Used by: All components + +## Data Flow + +**Navigation Flow:** + +1. User clicks sidebar menu item +2. React Router `` handles navigation +3. `routes.ts` matches path to view component +4. `DashboardLayout` renders with `` for view +5. View component mounts and renders content +6. UI components receive props and render + +**State Management:** +- **Local component state only** - No Redux, Zustand, or Context API for global state +- Sidebar collapsed state: `DashboardLayout.tsx` (useState) +- Menu expanded items: `Sidebar.tsx` (useState) +- Form data: Managed within each view component +- Time/status: `Header.tsx` (useState + useEffect) + +## Key Abstractions + +**View Component Pattern:** +- Purpose: Page-level route handlers +- Examples: `sample_interface/src/app/components/views/RainfallView.tsx`, `sample_interface/src/app/components/views/ADCSettingView.tsx` +- Pattern: Function component that returns JSX with Card-based layouts + +**UI Component Pattern (shadcn/ui):** +- Purpose: Atomic reusable components +- Examples: `sample_interface/src/app/components/ui/button.tsx`, `sample_interface/src/app/components/ui/card.tsx` +- Pattern: Compositional components with `cn()` utility for class merging +- Sub-pattern: Each component exports named exports (e.g., `Card`, `CardHeader`, `CardContent`) + +**Utility Pattern:** +- Purpose: Shared helper functions +- Examples: `sample_interface/src/app/components/ui/utils.ts` (cn function) +- Pattern: Named exports, single responsibility + +## Entry Points + +**Application Entry:** +- Location: `sample_interface/src/app/App.tsx` +- Triggers: Vite dev server or production build +- Responsibilities: Provides RouterProvider with configured router + +**Routing Entry:** +- Location: `sample_interface/src/app/routes.ts` +- Triggers: Browser URL changes +- Responsibilities: Defines all routes, maps paths to view components + +**Style Entry:** +- Location: `sample_interface/src/styles/index.css` +- Triggers: Component rendering +- Responsibilities: Imports fonts, Tailwind, theme variables + +## Error Handling + +**Strategy:** No centralized error handling detected + +**Patterns:** +- Components render static content with no error boundaries +- Form validation handled inline within views +- No try/catch blocks observed in view components +- Image fallback component: `sample_interface/src/app/components/figma/ImageWithFallback.tsx` + +## Cross-Cutting Concerns + +**Logging:** Console-based (no logging framework detected) + +**Validation:** Inline form validation within view components + +**Authentication:** UI-only in LoginView.tsx, no auth flow implemented + +**Theming:** Tailwind CSS with dark color palette (gray-900, gray-950 base) + +--- + +*Architecture analysis: 2025-03-13* diff --git a/.planning/codebase/CONCERNS.md b/.planning/codebase/CONCERNS.md new file mode 100644 index 000000000..cdd43c9b8 --- /dev/null +++ b/.planning/codebase/CONCERNS.md @@ -0,0 +1,208 @@ +# Codebase Concerns + +**Analysis Date:** 2026-03-13 + +## Tech Debt + +**Mock Data Throughout Application:** +- Issue: All views contain hardcoded mock data instead of real API integrations +- Files: + - `src/app/components/views/FlashMemoryView.tsx` (lines 6-25) + - `src/app/components/views/RainfallView.tsx` (lines 5-10, 43-49) + - `src/app/components/views/ADCSettingView.tsx` (lines 8-13) + - `src/app/components/views/CalibrationView.tsx` (lines 6-11) + - `src/app/components/views/StationInfoView.tsx` (lines 5-14) + - `src/app/components/views/Header.tsx` (lines 56, 77, 91, 97) +- Impact: Application is not functional for production use; requires complete rewrite of data layer +- Fix approach: Implement API client layer, create custom hooks for data fetching (useApi, useSensorData), replace all mock constants with API calls + +**Missing API Integration Layer:** +- Issue: No HTTP client configured, no API service layer exists +- Files: All view files in `src/app/components/views/` +- Impact: Forms don't submit, data doesn't persist, application is read-only demo +- Fix approach: Add axios or fetch wrapper, create service modules in `src/app/services/` for each domain (sensors, settings, auth) + +**Placeholder Components:** +- Issue: GraphView contains only placeholder content with no chart implementation +- File: `src/app/components/views/GraphView.tsx` (lines 17-19) +- Impact: Core feature is non-functional despite chart component existing (`src/app/components/ui/chart.tsx`) +- Fix approach: Integrate Recharts with actual data source + +## Known Issues + +**Exposed Default Credentials:** +- Issue: Login page displays hardcoded default credentials in the UI +- File: `src/app/components/views/LoginView.tsx` (lines 54-56) +- Content: "Default credentials: admin / admin" +- Impact: Security vulnerability - exposes authentication credentials to all users +- Fix approach: Remove credential hints from UI, implement secure password reset flow, store credentials server-side only + +**Non-Functional Interactive Elements:** +- Issue: Buttons and actions don't perform actual operations +- Files: + - `src/app/components/views/FlashMemoryView.tsx`: Download and Delete buttons (lines 80-87) are non-functional + - `src/app/components/views/SettingView.tsx`: Factory Reset and Reboot System buttons (lines 67-71) lack confirmation dialogs + - `src/app/components/views/GPRSSettingView.tsx`: Test Connection button (lines 60-62) has no implementation +- Impact: Users receive no feedback, destructive actions can occur accidentally +- Fix approach: Implement action handlers, add confirmation dialogs for destructive operations, add toast notifications for user feedback + +## Security Considerations + +**No Authentication Implementation:** +- Risk: Login form is UI-only with no auth logic +- File: `src/app/components/views/LoginView.tsx` - form submission not handled +- Current mitigation: None +- Recommendations: Implement JWT or session-based auth, add ProtectedRoute wrapper, store auth token securely (httpOnly cookies preferred) + +**Missing Input Validation:** +- Risk: All forms accept any input without validation +- Files: All form-containing views (`*SettingView.tsx`) +- Current mitigation: None +- Recommendations: Add Zod or Yup schemas for form validation, validate on blur and submit, display inline error messages + +**No HTTPS Enforcement:** +- Risk: Application may run over unencrypted connections +- Current mitigation: None visible +- Recommendations: Add HSTS headers, enforce HTTPS in production builds, validate API URLs use HTTPS + +**Hardcoded Sensitive-Looking Configuration:** +- Risk: Device configuration values exposed in source +- Files: + - `src/app/components/views/StationInfoView.tsx`: Hardcoded station coordinates and serial numbers (lines 5-14) + - `src/app/components/views/Header.tsx`: Hardcoded station ID "STN-001" (line 56) +- Current mitigation: None +- Recommendations: Move configuration to environment variables or secure config endpoint + +## Performance Bottlenecks + +**Large Component Files:** +- Problem: sidebar.tsx is 726 lines, violating single responsibility principle +- File: `src/app/components/ui/sidebar.tsx` +- Cause: Multiple components (SidebarProvider, Sidebar, SidebarTrigger, SidebarRail, etc.) in one file +- Improvement path: Split into separate files: `sidebar-provider.tsx`, `sidebar-trigger.tsx`, `sidebar-menu.tsx`, etc. + +**No Code Splitting:** +- Problem: All routes loaded upfront in single bundle +- File: `src/app/routes.ts` - static imports of all view components +- Cause: No lazy loading or dynamic imports +- Improvement path: Use React.lazy() and Suspense for route-based code splitting + +**Direct DOM Manipulation:** +- Problem: NavigationButtons uses imperative DOM access instead of React refs +- File: `src/app/components/views/NavigationButtons.tsx` (lines 8-19) +- Code: `document.getElementById("details-panel")` +- Improvement path: Use React ref forwarded from DashboardLayout, or use scroll context + +## Fragile Areas + +**Chart Component Null Returns:** +- Files: `src/app/components/ui/chart.tsx` (lines 78, 133, 153, 168, 267) +- Issue: Multiple early `return null` statements may cause React reconciliation issues +- Safe modification: Ensure parent components handle null returns gracefully, add error boundaries + +**Form State Management:** +- Issue: All forms use uncontrolled inputs with defaultValue only +- Files: All `*SettingView.tsx` files +- Why fragile: Form state not tracked, can't validate, can't persist, can't show pending state +- Safe modification: Convert to controlled inputs with useState, or use React Hook Form library + +**Hardcoded Route Paths:** +- Issue: Route paths defined in multiple places +- Files: + - `src/app/routes.ts` - route definitions + - `src/app/components/Sidebar.tsx` (lines 39-87) - navigation links +- Why fragile: Route changes require updates in multiple files, easy to miss one +- Safe modification: Create `src/app/constants/routes.ts` with path constants, use throughout app + +**No Error Boundaries:** +- Issue: Single component error can crash entire application +- Current state: No ErrorBoundary component found +- Safe modification: Add error boundaries at route level and around complex components + +## Scaling Limits + +**Current Capacity:** +- 72 source files, ~13,300 lines of TypeScript +- No test coverage +- All data hardcoded (no real data volume) + +**Limitations:** +- No pagination implementation for data lists +- No virtualization for long lists +- No caching strategy + +**Scaling Path:** +- Implement React Query or SWR for server state management +- Add virtualized lists for large datasets +- Implement proper pagination in data views + +## Dependencies at Risk + +**React Router v7 Migration:** +- Current: `react-router` version 7.13.0 +- Risk: Recently released major version, API may change +- Impact: Route definitions in `src/app/routes.ts` use newer createBrowserRouter API +- Migration plan: Monitor for breaking changes, lock version if needed + +**Tailwind CSS v4:** +- Current: Version 4.1.12 with @theme inline syntax +- Risk: New major version with different configuration approach +- Impact: theme.css uses new v4 syntax +- Migration plan: Maintain lockfile, test before upgrades + +## Missing Critical Features + +**Real-Time Data Updates:** +- Problem: Dashboard shows static values, no live sensor data +- Blocks: Production deployment for monitoring use cases +- Priority: High + +**Form Validation:** +- Problem: No validation on any input fields +- Files: All `*SettingView.tsx` files +- Blocks: Data integrity, user experience +- Priority: High + +**Error Handling:** +- Problem: No error states, no user feedback for failures +- Blocks: Production reliability +- Priority: High + +**API Integration:** +- Problem: No backend communication +- Blocks: All CRUD operations +- Priority: Critical + +**Authentication/Authorization:** +- Problem: Login form is decorative only +- Blocks: Security requirements +- Priority: Critical + +**Confirmation Dialogs:** +- Problem: Destructive actions (Factory Reset, Reboot, Delete) have no confirmation +- Files: `src/app/components/views/SettingView.tsx`, `src/app/components/views/FlashMemoryView.tsx` +- Priority: Medium + +## Test Coverage Gaps + +**No Testing Infrastructure:** +- What's not tested: Everything (100% gap) +- Files: Zero test files found +- Risk: No regression protection, no confidence in changes +- Priority: Critical + +**Recommended Testing Stack:** +- Unit tests: Vitest + React Testing Library for components +- Integration tests: Test form submissions, navigation flows +- E2E tests: Playwright for critical user journeys + +**Critical Test Priorities:** +1. Form validation and submission flows +2. Authentication state management +3. Data fetching and error handling +4. Navigation and routing +5. Settings persistence + +--- + +*Concerns audit: 2026-03-13* diff --git a/.planning/codebase/CONVENTIONS.md b/.planning/codebase/CONVENTIONS.md new file mode 100644 index 000000000..d0efb0598 --- /dev/null +++ b/.planning/codebase/CONVENTIONS.md @@ -0,0 +1,256 @@ +# Coding Conventions + +**Analysis Date:** 2026-03-13 + +## Overview + +This codebase follows conventions documented in `/sample_interface/guidelines/Guidelines.md` with React/TypeScript patterns optimized for a touchscreen industrial dashboard interface. + +## Naming Patterns + +### Files +- **Components:** PascalCase with `.tsx` extension (e.g., `RainfallView.tsx`, `Header.tsx`) +- **Views:** `[Feature]View.tsx` pattern (e.g., `SettingView.tsx`, `LoginView.tsx`) +- **UI Components:** Lowercase with hyphen separation (e.g., `button.tsx`, `card.tsx`) +- **Utilities:** camelCase (e.g., `utils.ts`) +- **Configuration:** `.config.ts` or `.config.mjs` (e.g., `vite.config.ts`, `postcss.config.mjs`) + +### Functions & Variables +- **Functions:** camelCase (e.g., `scrollUp()`, `toggleExpanded()`, `formatTime()`) +- **React Components:** PascalCase (e.g., `function Card()`, `function Header()`) +- **State Variables:** camelCase with `is`/`has`/`should` prefix for booleans + - `const [sidebarCollapsed, setSidebarCollapsed] = useState(false)` + - `const [isOnline, setIsOnline] = useState(true)` + - `const [selectedFile, setSelectedFile] = useState(...)` +- **Constants:** camelCase for objects/arrays, UPPERCASE for true constants + - `const menuItems = [...]` + - `const scrollAmount = 300` + +### Props & Types +- **Props Interface:** `[ComponentName]Props` (e.g., `SidebarProps`, `MenuItem`) +- **Type Parameters:** PascalCase (e.g., `TFieldValues`, `TName`) +- **Event Handlers:** `on[Action]` prefix (e.g., `onToggle`, `onClick`) + +## Code Style + +### Formatting +- **No automated linting/formatting configured** (no ESLint, Prettier, or Biome detected) +- Indentation: 2 spaces +- Semicolons: Used consistently +- Quotes: Double quotes for strings +- Trailing commas: Not used consistently + +### Component Structure +```typescript +// Named function declaration (preferred) +function Button({ className, variant, ...props }: ButtonProps) { + return ; +} + +// Arrow function for simpler components +export const router = createBrowserRouter([...]); + +// Export at end of file for UI components +export { Button, buttonVariants }; +``` + +## Import Organization + +### Order +1. **React imports:** `import * as React from "react"` +2. **External libraries:** Radix UI, React Router, Lucide icons +3. **Internal components:** Relative paths from current file +4. **Utilities:** Local utility functions + +### Examples +```typescript +// From button.tsx +import * as React from "react"; +import { Slot } from "@radix-ui/react-slot"; +import { cva, type VariantProps } from "class-variance-authority"; +import { cn } from "./utils"; + +// From views +import { Card, CardContent } from "../ui/card"; +import { Button } from "../ui/button"; +import { Settings } from "lucide-react"; +``` + +### Path Aliases +- `@/` maps to `src/` directory (configured in `vite.config.ts`) +- Currently used in minimal places; relative imports preferred in existing code + +## Component Patterns + +### shadcn/ui Pattern +Components follow the shadcn/ui design pattern: +```typescript +// 1. Import React as namespace +import * as React from "react"; + +// 2. Use React.ComponentProps for HTML element props +function Card({ className, ...props }: React.ComponentProps<"div">) { + return ( +
+ ); +} + +// 3. Export at end +export { Card, CardHeader, ... }; +``` + +### View Components +Views follow consistent structure: +```typescript +export function ViewName() { + // Local state and data + const data = [...]; + + return ( +
+ {/* Header with icon and title */} +
+ +

Title

+
+ + {/* Content cards */} + ... +
+ ); +} +``` + +## Styling Conventions + +### Tailwind CSS Usage +- **Primary styling method:** Tailwind utility classes +- **Dark theme default:** All components styled for dark UI +- **Custom colors:** Extended via CSS variables in `theme.css` + +### Color Palette +- Backgrounds: `bg-gray-900` (primary), `bg-gray-950` (elevated), `bg-gray-800` (inputs) +- Primary actions: `bg-blue-600 hover:bg-blue-700` +- Success: `text-green-400`, Warning: `text-yellow-400`, Error: `text-red-400` +- Borders: `border-gray-700` + +### Class Name Utility +All UI components use `cn()` utility from `utils.ts`: +```typescript +import { clsx, type ClassValue } from "clsx"; +import { twMerge } from "tailwind-merge"; + +export function cn(...inputs: ClassValue[]) { + return twMerge(clsx(inputs)); +} +``` + +### Touchscreen-First Design +- Minimum touch targets: 44x44px (preferably 56x56px) +- Button sizing: `h-14 w-14` for navigation, `h-9` for standard buttons +- Spacing: `p-3` or `p-4` for adequate touch area + +## State Management + +### Local State +- React `useState` for component-level state +- `useEffect` for side effects (timers, subscriptions) +- No global state management library detected + +### Router State +- React Router v7 for routing +- `useLocation()` for current path +- URL as source of truth for navigation state + +## Error Handling + +### Patterns +- Minimal explicit error handling in UI code +- Form validation via react-hook-form (in `form.tsx`) +- Console errors for development debugging + +### Type Safety +- TypeScript strict mode implied by usage +- Type imports using `type` keyword: `import { type ClassValue }` +- Generic components with proper type constraints + +## Comments + +### Guidelines +- Minimal inline comments +- Component purpose inferred from file name and structure +- Complex logic may have inline explanations + +### JSDoc/TSDoc +- Not used extensively +- Type definitions provide documentation + +## Function Design + +### Size +- Components: Typically 30-120 lines +- View components: 50-110 lines each +- UI components: 20-90 lines each + +### Parameters +- Destructured props with explicit typing +- Spread operator for passing through remaining props +- Default values inline in destructuring + +### Return Values +- JSX.Element for React components +- Void for event handlers +- Typed arrays/objects for data functions + +## Module Design + +### Exports +- Named exports for all components (no default exports except App.tsx) +- Grouped exports at end of file for UI components +- Re-exports from barrel files not used + +### File Organization +``` +src/app/ +├── App.tsx # Default export, entry point +├── routes.ts # Named export for router config +├── components/ +│ ├── [Layout].tsx # Named exports +│ ├── ui/ # UI primitives +│ │ └── [component].tsx +│ └── views/ # Page views +│ └── [View].tsx +└── styles/ + └── *.css +``` + +## Special Conventions + +### Touchscreen Interface +- No scrollbars visible (hidden via CSS) +- Navigation via fixed Up/Down buttons +- Fixed button positioning: `fixed top-20 right-4` + +### Data Display Pattern +- Icon + Title header for all views +- Card-based content organization +- Color-coded data categories + +### Status Indicators +- Icon + text pattern: `` +- Dot indicators: `w-2 h-2 rounded-full` + +## Configuration Files + +- **`vite.config.ts`:** Build configuration with path alias +- **`postcss.config.mjs`:** PostCSS (minimal - Tailwind handles processing) +- **`package.json`:** Scripts limited to `build` +- **No lint/format config detected:** No ESLint, Prettier, or Biome configuration + +--- + +*Convention analysis: 2026-03-13* diff --git a/.planning/codebase/INTEGRATIONS.md b/.planning/codebase/INTEGRATIONS.md new file mode 100644 index 000000000..da4caef92 --- /dev/null +++ b/.planning/codebase/INTEGRATIONS.md @@ -0,0 +1,190 @@ +# External Integrations + +**Analysis Date:** 2026-03-13 + +## APIs & External Services + +**Backend API Integration:** +- **Status:** Not yet implemented +- **Evidence:** No fetch/axios/API client code found in source files +- **Pattern Used:** Static mock data in view components + +**Current Data Approach:** +- All data is hardcoded/mock data within components +- Examples: + - `RainfallView.tsx` - Static rainfall data array + - `StationInfoView.tsx` - Hardcoded station information + - `FlashMemoryView.tsx` - Mock file list and content + - `ADCSettingView.tsx` - Mock ADC channel readings + - `CalibrationView.tsx` - Mock sensor calibration status + +**Planned Integration Points:** +Based on view structure, expected API endpoints include: +- `/api/rainfall` - Rainfall measurement data +- `/api/station` - Station configuration and status +- `/api/adc` - ADC channel readings +- `/api/calibration` - Sensor calibration data +- `/api/files` - Flash memory file management +- `/api/gprs` - GPRS settings and connectivity +- `/api/network` - Network configuration +- `/api/auth` - Authentication (login/logout) + +## Data Storage + +**Databases:** +- **Type:** None detected in frontend +- **Pattern:** This is a pure frontend application +- **Expected Backend:** RTU device likely exposes REST API or WebSocket + +**File Storage:** +- **Frontend:** Local filesystem access not implemented +- **Flash Memory View:** Mock file browser interface (UI only) +- **Expected:** File download/upload via API to device storage + +**Caching:** +- **Current:** React state only (useState) +- **No external caching libraries detected** + +## Authentication & Identity + +**Auth Provider:** +- **Status:** UI only - Login form present but not functional +- **Location:** `src/app/components/views/LoginView.tsx` +- **Current:** Static credentials display ("admin / admin") +- **Implementation:** Basic form without API integration + +**Auth Pattern:** +- Username/password form +- "Remember me" checkbox (localStorage potential) +- Login status indicator in header (mock state) +- Expected: JWT or session-based auth with backend + +## Monitoring & Observability + +**Error Tracking:** +- **Service:** None detected +- **Implementation:** No error boundaries or logging framework + +**Logs:** +- **Approach:** Console logging only (default) +- **No structured logging detected** + +## Communication Protocols + +**GPRS/Cellular:** +- **UI Location:** `src/app/components/views/GPRSSettingView.tsx` +- **Configuration:** Server URL, Port, Upload Interval settings +- **Integration:** Form UI only - no actual GPRS client code + +**Network Setup:** +- **UI Location:** `src/app/components/views/NetworkSetupView.tsx` +- **Expected:** IP configuration, DNS, Gateway settings + +**Mobile Setting:** +- **UI Location:** `src/app/components/views/MobileSettingView.tsx` +- **Purpose:** SMS/cellular configuration for RTU + +## Hardware Integration + +**ADC (Analog-to-Digital Converter):** +- **UI Location:** `src/app/components/views/ADCSettingView.tsx` +- **Channels:** 4 channels displayed (Water Level, Temperature, Pressure, Flow Rate) +- **Integration:** Voltage and raw value display expected from hardware + +**Sensors:** +- **Rainfall Sensor** - `RainfallView.tsx`, `RainfallSettingView.tsx` +- **Water Level Sensor** - `LevelSettingView.tsx` +- **Temperature/Pressure** - `ADCSettingView.tsx` +- **Evaporation Sensor** - `EVAPSettingView.tsx` +- **Siren Control** - `SirenSettingView.tsx` + +**Status Monitoring:** +- Header displays: Online status, battery voltage, solar voltage +- Mock state only - no real hardware polling + +## Environment Configuration + +**Required Environment Variables (Expected):** +Based on typical RTU applications: +``` +VITE_API_BASE_URL=http://device.local/api +VITE_WS_URL=ws://device.local/ws +VITE_DEVICE_ID=STN-001 +``` + +**Current State:** +- No `.env` files present +- No environment variable usage detected +- All values hardcoded + +**Secrets Location:** +- Not applicable (no backend integration yet) + +## Webhooks & Callbacks + +**Incoming:** +- None detected +- Expected: WebSocket for real-time sensor data + +**Outgoing:** +- None detected +- Expected: HTTP POST for data upload to server + +## CI/CD & Deployment + +**Hosting:** +- **Platform:** Figma Make (inferred from package name `@figma/my-make-file`) +- **Build Command:** `vite build` +- **Output:** Static SPA files in `dist/` + +**CI Pipeline:** +- None detected (no `.github/workflows`, `.gitlab-ci.yml`, etc.) + +## Integration Gaps + +**Missing Critical Integrations:** + +1. **Backend API Client** + - Missing: fetch/axios configuration + - Impact: Application shows only static data + - Recommendation: Add API client with error handling + +2. **WebSocket Connection** + - Missing: Real-time sensor data updates + - Impact: Manual refresh required for data updates + - Recommendation: Implement WebSocket for live data + +3. **Authentication Flow** + - Missing: Login/logout API integration + - Impact: Auth is UI-only + - Recommendation: Connect to device auth endpoint + +4. **File Operations** + - Missing: Download/delete API calls + - Impact: Flash memory is read-only mock + - Recommendation: Implement file API client + +5. **Hardware Commands** + - Missing: Save settings to device + - Impact: Settings forms don't persist + - Recommendation: Add POST endpoints for configuration + +## Third-Party Services Summary + +**Currently Integrated:** +| Service | Purpose | Location | +|---------|---------|----------| +| Lucide React | Icons | All view components | +| Radix UI | Accessible components | `src/app/components/ui/` | + +**Recommended for Integration:** +| Service | Purpose | Use Case | +|---------|---------|----------| +| axios/fetch | HTTP client | API communication | +| SWR/React Query | Data fetching | Caching and synchronization | +| zod | Validation | API response validation | +| WebSocket API | Real-time | Sensor data streaming | + +--- + +*Integration audit: 2026-03-13* diff --git a/.planning/codebase/STACK.md b/.planning/codebase/STACK.md new file mode 100644 index 000000000..27a01dcfc --- /dev/null +++ b/.planning/codebase/STACK.md @@ -0,0 +1,150 @@ +# Technology Stack + +**Analysis Date:** 2026-03-13 + +## Languages + +**Primary:** +- TypeScript (React) - All application logic and components +- CSS - Styling via Tailwind CSS with custom theme variables + +**Secondary:** +- JavaScript - Build tool configuration + +## Runtime + +**Environment:** +- Node.js (latest LTS recommended) + +**Package Manager:** +- pnpm (evidenced by `pnpm.overrides` in `package.json`) +- Lockfile: Not committed to repository + +## Frameworks + +**Core:** +- **React 18.3.1** - UI library with hooks and functional components + - Peer dependency (optional, for compatibility with Figma Make) +- **React Router 7.13.0** - Client-side routing with Data API mode + - Router configuration in `src/app/routes.ts` + - Uses `createBrowserRouter` for SPA navigation + +**UI Component Framework:** +- **Radix UI** - Headless accessible UI primitives + - 23 Radix primitives including: accordion, dialog, dropdown-menu, select, tabs, tooltip, etc. + - Provides accessibility and keyboard navigation out of the box + +**Styling:** +- **Tailwind CSS 4.1.12** - Utility-first CSS framework + - Integrated via `@tailwindcss/vite` plugin + - Custom theme configuration in `src/styles/theme.css` + - Uses CSS variables for theming with light/dark mode support + - Animation support via `tw-animate-css` + +**Animation:** +- **Framer Motion ("motion" package 12.23.24)** - React animation library + +## Build Tools + +**Build System:** +- **Vite 6.3.5** - Fast development server and production bundler + - Config: `vite.config.ts` + - Uses `@vitejs/plugin-react` for React support + - Path alias `@` configured to `./src` + - Asset support: `.svg`, `.csv` files + +**CSS Processing:** +- **PostCSS** - CSS transformation (via Vite plugin) + - Config: `postcss.config.mjs` (empty - Tailwind v4 handles this automatically) + +## Key Dependencies + +**Critical UI Components:** +- `@radix-ui/react-*` (23 packages) - Accessible UI primitives +- `class-variance-authority` 0.7.1 - Type-safe Tailwind variant generation +- `clsx` 2.1.1 - Conditional class name joining +- `tailwind-merge` 3.2.0 - Tailwind class deduplication +- `lucide-react` 0.487.0 - Icon library + +**Form & Input:** +- `react-hook-form` 7.55.0 - Form state management and validation +- `cmdk` 1.1.1 - Command palette/Combobox component +- `input-otp` 1.4.2 - OTP input component + +**Data Visualization:** +- `recharts` 2.15.2 - React charting library + +**Date Handling:** +- `date-fns` 3.6.0 - Date formatting and manipulation +- `react-day-picker` 8.10.1 - Date picker component + +**Theming:** +- `next-themes` 0.4.6 - Theme switching (dark/light mode) + +**Notifications:** +- `sonner` 2.0.3 - Toast notifications + +**Carousels & Layout:** +- `embla-carousel-react` 8.6.0 - Touch carousel +- `react-resizable-panels` 2.1.7 - Resizable panel layouts +- `react-responsive-masonry` 2.7.1 - Masonry grid layout + +**Drag & Drop:** +- `react-dnd` 16.0.1 + `react-dnd-html5-backend` 16.0.1 - Drag and drop functionality + +**Drawer/Modal:** +- `vaul` 1.1.2 - Drawer component for mobile + +**Slider:** +- `react-slick` 0.31.0 - Image/content carousel + +**Optional/Peer Dependencies:** +- `@emotion/react` / `@emotion/styled` - CSS-in-JS (for MUI compatibility) +- `@mui/material` / `@mui/icons-material` - Material UI (peer dependency for Figma Make) + +## Configuration + +**Environment:** +- No `.env` file detected in repository +- Configuration appears to be hardcoded or passed at build time +- No environment-specific configs visible + +**Build:** +- `vite.config.ts` - Vite configuration with React and Tailwind plugins +- `postcss.config.mjs` - Empty config (Tailwind v4 handles PostCSS internally) +- `tsconfig.json` - Not present in repository (TypeScript handled by Vite) + +## Platform Requirements + +**Development:** +- Node.js (latest LTS) +- pnpm package manager +- Modern browser with ES2020+ support + +**Production:** +- Static file hosting (SPA) +- Target: 7-inch industrial touchscreen displays (800x480 to 1024x600) +- Optimized for landscape orientation +- Touch-friendly interface design + +**Browser Support:** +- Modern Chromium-based browsers (Chrome, Edge) +- WebKit (Safari) +- Firefox (ESR) + +## Notable Architecture Decisions + +**Design System:** +- Uses shadcn/ui pattern (Radix + Tailwind + CVA) +- Custom theme tokens defined in CSS variables +- Dark theme by default for industrial use +- Touch-optimized sizing (minimum 44x44px touch targets) + +**Component Organization:** +- UI components: `src/app/components/ui/` +- View components: `src/app/components/views/` +- Layout components: `src/app/components/` (root level) + +--- + +*Stack analysis: 2026-03-13* diff --git a/.planning/codebase/STRUCTURE.md b/.planning/codebase/STRUCTURE.md new file mode 100644 index 000000000..ea263b197 --- /dev/null +++ b/.planning/codebase/STRUCTURE.md @@ -0,0 +1,167 @@ +# Codebase Structure + +**Analysis Date:** 2025-03-13 + +## Directory Layout + +``` +sample_interface/ +├── src/ +│ ├── app/ +│ │ ├── App.tsx # Application entry point +│ │ ├── routes.ts # Route definitions +│ │ └── components/ +│ │ ├── DashboardLayout.tsx # Main layout shell +│ │ ├── Header.tsx # Top status bar +│ │ ├── NavigationButtons.tsx # Scroll controls +│ │ ├── Sidebar.tsx # Navigation sidebar +│ │ ├── figma/ +│ │ │ └── ImageWithFallback.tsx +│ │ ├── ui/ # 40+ shadcn/ui components +│ │ │ ├── button.tsx +│ │ │ ├── card.tsx +│ │ │ ├── input.tsx +│ │ │ ├── utils.ts +│ │ │ └── ... +│ │ └── views/ # Page/route components +│ │ ├── ADCSettingView.tsx +│ │ ├── CalibrationView.tsx +│ │ ├── DateTimeSettingView.tsx +│ │ ├── EVAPSettingView.tsx +│ │ ├── FlashMemoryView.tsx +│ │ ├── GPRSSettingView.tsx +│ │ ├── GraphView.tsx +│ │ ├── LevelSettingView.tsx +│ │ ├── LoginView.tsx +│ │ ├── MobileSettingView.tsx +│ │ ├── NetworkSetupView.tsx +│ │ ├── RainfallSettingView.tsx +│ │ ├── RainfallView.tsx +│ │ ├── SettingView.tsx +│ │ ├── SirenSettingView.tsx +│ │ └── StationInfoView.tsx +│ └── styles/ +│ ├── index.css # Main stylesheet entry +│ ├── tailwind.css # Tailwind imports +│ └── theme.css # Theme variables +├── guidelines/ +│ └── Guidelines.md # Design system documentation +├── package.json # Dependencies +├── postcss.config.mjs # PostCSS configuration +└── vite.config.ts # Vite build configuration +``` + +## Directory Purposes + +**src/app/:** +- Purpose: Application logic and component tree +- Contains: Entry point, routing, components +- Key files: `App.tsx`, `routes.ts` + +**src/app/components/:** +- Purpose: Layout and structural components +- Contains: DashboardLayout, Header, Sidebar, NavigationButtons +- Key files: `DashboardLayout.tsx`, `Sidebar.tsx` + +**src/app/components/ui/:** +- Purpose: shadcn/ui primitive components +- Contains: 40+ UI components (button, card, input, etc.) +- Key files: `utils.ts` (cn function), `button.tsx`, `card.tsx` +- Pattern: Each component in separate file with PascalCase naming + +**src/app/components/views/:** +- Purpose: Route/page-level components +- Contains: 16 view components (one per route) +- Key files: `RainfallView.tsx` (default), `LoginView.tsx`, `GraphView.tsx` +- Pattern: `{Name}View.tsx` naming convention + +**src/app/components/figma/:** +- Purpose: Figma-related utilities +- Contains: `ImageWithFallback.tsx` +- Usage: Image loading with error fallback + +**src/styles/:** +- Purpose: Global styles and CSS configuration +- Contains: CSS imports and theme definitions +- Key files: `index.css` (entry), `tailwind.css`, `theme.css` + +**guidelines/:** +- Purpose: Design system documentation +- Contains: `Guidelines.md` (458 lines of design specs) +- Usage: Color palette, typography, spacing standards + +## Key File Locations + +**Entry Points:** +- `sample_interface/src/app/App.tsx`: React application root +- `sample_interface/src/app/routes.ts`: Route configuration +- `sample_interface/src/styles/index.css`: Style entry + +**Configuration:** +- `sample_interface/vite.config.ts`: Vite build config with @ alias +- `sample_interface/package.json`: Dependencies (React 18, React Router 7, Radix, Tailwind 4) +- `sample_interface/postcss.config.mjs`: PostCSS configuration + +**Core Layout:** +- `sample_interface/src/app/components/DashboardLayout.tsx`: Main layout with Outlet +- `sample_interface/src/app/components/Sidebar.tsx`: Navigation with 7 menu items +- `sample_interface/src/app/components/Header.tsx`: Status bar with time, connection, battery + +**Core UI:** +- `sample_interface/src/app/components/ui/utils.ts`: `cn()` class merging utility +- `sample_interface/src/app/components/ui/button.tsx`: Primary button component +- `sample_interface/src/app/components/ui/card.tsx`: Card container component + +## Naming Conventions + +**Files:** +- Components: PascalCase.tsx (e.g., `RainfallView.tsx`, `Button.tsx`) +- Utilities: camelCase.ts (e.g., `utils.ts`) +- Config: kebab-case.ts (e.g., `vite.config.ts`) +- Styles: lowercase.css (e.g., `index.css`) + +**Directories:** +- Lowercase: `ui/`, `views/`, `styles/`, `figma/` + +**Exports:** +- Components: Named exports (e.g., `export function Button`) +- Utilities: Named exports (e.g., `export function cn`) +- View suffix: All route components end with `View` (e.g., `RainfallView`, `LoginView`) + +## Where to Add New Code + +**New Route/View:** +- Implementation: `sample_interface/src/app/components/views/{Name}View.tsx` +- Registration: `sample_interface/src/app/routes.ts` (add to children array) +- Menu item: `sample_interface/src/app/components/Sidebar.tsx` (add to menuItems array) + +**New UI Component:** +- Implementation: `sample_interface/src/app/components/ui/{component}.tsx` +- Pattern: Follow shadcn/ui style with `cn()` utility +- Re-export from other components as needed + +**New Layout Component:** +- Implementation: `sample_interface/src/app/components/{Component}.tsx` +- Import in: `DashboardLayout.tsx` or `Sidebar.tsx` as needed + +**Styles/Theme:** +- Global styles: `sample_interface/src/styles/theme.css` +- Tailwind config: `sample_interface/vite.config.ts` (Tailwind v4 uses CSS config) + +## Special Directories + +**sample_interface/src/app/components/ui/:** +- Purpose: shadcn/ui component library +- Generated: Partially (shadcn init pattern) +- Committed: Yes +- Note: 40+ components from Radix UI primitives + +**sample_interface/guidelines/:** +- Purpose: Design documentation +- Generated: No (manually maintained) +- Committed: Yes +- Note: Contains 458 lines of design system specs + +--- + +*Structure analysis: 2025-03-13* diff --git a/.planning/codebase/TESTING.md b/.planning/codebase/TESTING.md new file mode 100644 index 000000000..6b534fc46 --- /dev/null +++ b/.planning/codebase/TESTING.md @@ -0,0 +1,249 @@ +# Testing Patterns + +**Analysis Date:** 2026-03-13 + +## Test Infrastructure + +**Status: NO TESTING INFRASTRUCTURE DETECTED** + +The codebase currently lacks automated testing configuration and test files. + +## Test Framework + +**Runner:** Not configured +- No Jest configuration detected +- No Vitest configuration detected +- No Playwright/Cypress configuration detected + +**Assertion Library:** Not configured +- No testing libraries in dependencies + +**Run Commands:** Not available +- `package.json` only defines: `"build": "vite build"` +- No test scripts present + +## Test File Organization + +**Current State:** +- No test files in source code (`*.test.ts`, `*.spec.ts`, `*.test.tsx`, `*.spec.tsx`) +- All test file matches were from `node_modules/` (zod library tests) + +**File Pattern:** Not established + +**Test Directory Structure:** Not implemented + +## Code Quality Indicators + +### TODO/FIXME Comments +Minimal technical debt markers found: +- `MobileSettingView.tsx` line 31: `placeholder="+63 XXX XXX XXXX"` (placeholder text, not TODO) + +### Code Complexity +View component line counts (reasonable for view components): +``` +FlashMemoryView.tsx 112 lines +ADCSettingView.tsx 83 lines +LevelSettingView.tsx 78 lines +MobileSettingView.tsx 70 lines +RainfallSettingView.tsx 69 lines +NetworkSetupView.tsx 69 lines +DateTimeSettingView.tsx 65 lines +CalibrationView.tsx 63 lines +RainfallView.tsx 63 lines +SettingView.tsx 76 lines +LoginView.tsx 61 lines +GraphView.tsx 51 lines +EVAPSettingView.tsx 54 lines +SirenSettingView.tsx 71 lines +GPRSSettingView.tsx 68 lines +StationInfoView.tsx 40 lines +``` + +**Total view code:** ~1,092 lines across 16 view files + +### Component Complexity +UI components (`src/app/components/ui/`): +- Range: 6 lines (`utils.ts`) to 168 lines (`form.tsx`) +- Most components: 20-90 lines +- Pattern: Small, focused components following shadcn/ui conventions + +## Missing Testing Infrastructure + +### Critical Gaps +1. **No unit test framework** - Components cannot be unit tested +2. **No integration tests** - Route integration untested +3. **No E2E tests** - User flows untested +4. **No test scripts** - No CI/CD integration possible +5. **No mocking strategy** - External dependencies not mockable + +### Testing Dependencies to Add +For comprehensive testing, the following would be needed: + +```json +{ + "devDependencies": { + "vitest": "^2.x", + "@testing-library/react": "^14.x", + "@testing-library/jest-dom": "^6.x", + "@testing-library/user-event": "^14.x", + "jsdom": "^24.x" + } +} +``` + +Or alternatively with Jest: + +```json +{ + "devDependencies": { + "jest": "^29.x", + "@testing-library/react": "^14.x", + "@testing-library/jest-dom": "^6.x", + "ts-jest": "^29.x", + "jest-environment-jsdom": "^29.x" + } +} +``` + +## Recommended Testing Strategy + +### Priority 1: Unit Tests for UI Components +Test critical UI primitives in `src/app/components/ui/`: +- `button.tsx` - Variant rendering, click handling +- `card.tsx` - Composition pattern +- `input.tsx` - Value handling, focus states +- `switch.tsx` - Toggle behavior + +### Priority 2: View Component Tests +Test user interactions in views: +- Form submissions +- State changes +- Navigation triggers + +### Priority 3: Integration Tests +Test route configuration: +- Route rendering +- Navigation flow +- Layout composition + +## Testing Conventions to Establish + +### Test File Naming +Recommended pattern (when tests are added): +- Co-located: `[Component].test.tsx` next to `[Component].tsx` +- Or separate: `__tests__/[Component].test.tsx` + +### Test Structure (Recommended) +```typescript +// button.test.tsx - Example pattern to follow +import { describe, it, expect, vi } from 'vitest'; +import { render, screen, fireEvent } from '@testing-library/react'; +import { Button } from './button'; + +describe('Button', () => { + it('renders with default variant', () => { + render(); + expect(screen.getByText('Click me')).toBeInTheDocument(); + }); + + it('handles click events', () => { + const handleClick = vi.fn(); + render(); + fireEvent.click(screen.getByText('Click me')); + expect(handleClick).toHaveBeenCalled(); + }); + + it('renders different variants', () => { + const { rerender } = render(); + // Assert destructive styling + + rerender(); + // Assert outline styling + }); +}); +``` + +### Mocking Strategy (Recommended) + +**External Libraries:** +- Mock `lucide-react` icons for snapshot stability +- Mock `@radix-ui` components at boundary + +**Browser APIs:** +- Mock `document.getElementById()` for scroll tests +- Mock `window` events if needed + +**Example Mock Pattern:** +```typescript +// Mock scroll behavior +const scrollByMock = vi.fn(); +Object.defineProperty(document, 'getElementById', { + value: vi.fn(() => ({ scrollBy: scrollByMock })), +}); +``` + +## Coverage Recommendations + +### Minimum Targets +- **UI Components:** 80% coverage (small, critical components) +- **View Components:** 60% coverage (user interaction paths) +- **Utility Functions:** 90% coverage (business logic) +- **Routes:** Integration tests for all paths + +### Critical Paths to Test +1. Login form submission +2. Sidebar navigation +3. File selection in FlashMemoryView +4. Settings toggle switches +5. Navigation button scrolling + +## CI/CD Integration + +### GitHub Actions (Recommended) +When tests are added, include in workflow: + +```yaml +name: Test +on: [push, pull_request] +jobs: + test: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - uses: pnpm/action-setup@v2 + - run: pnpm install + - run: pnpm test + - run: pnpm test:coverage +``` + +## Testing Documentation Gap + +**Issue:** No testing guidelines in existing documentation + +The `Guidelines.md` file (458 lines) covers: +- Design patterns +- Color palettes +- Component naming +- Touchscreen guidelines + +But does NOT cover: +- Testing conventions +- Test file organization +- Mocking patterns +- Coverage requirements + +## Action Items for Testing + +1. **Add testing dependencies** (Vitest + React Testing Library recommended) +2. **Create `vitest.config.ts`** with jsdom environment +3. **Add test scripts** to `package.json` +4. **Write initial tests** for critical UI components +5. **Document testing patterns** in Guidelines.md +6. **Set up CI/CD** to run tests on PR +7. **Establish coverage thresholds** + +--- + +*Testing analysis: 2026-03-13* + +**Summary:** This codebase currently has no testing infrastructure. All testing patterns documented above are recommendations for implementation rather than observed conventions.