rtu_v5/.planning/codebase/ARCHITECTURE.md

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 <Link> handles navigation
3. routes.ts matches path to view component
4. DashboardLayout renders with <Outlet /> 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