sp80/.planning/codebase/STRUCTURE.md

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