# WebUI Directory Structure

This document describes the refactored, organized structure of the WebUI.

## Overview

The WebUI follows a feature-based architecture with clear separation of concerns:

```
webui/
├── app/                    # Next.js App Router (pages and layouts)
│   ├── (auth)/            # Auth-protected routes
│   ├── globals.css        # Global styles
│   ├── layout.tsx         # Root layout
│   └── page.tsx           # Home page
├── components/            # React components
│   ├── features/         # Feature-specific components
│   │   ├── image-generation/
│   │   ├── models/
│   │   ├── queue/
│   │   └── index.ts
│   ├── forms/            # Form components
│   ├── layout/           # Layout and navigation
│   ├── ui/               # Reusable UI primitives
│   └── index.ts          # Component barrel exports
├── lib/                  # Core utilities and services
│   ├── hooks/            # Custom React hooks
│   ├── services/         # API and external services
│   ├── types/            # TypeScript type definitions
│   ├── utils/            # Utility functions
│   └── index.ts          # Library barrel exports
├── public/               # Static assets
└── contexts/             # React context providers
```

## Component Organization

### Features

Feature components are organized by domain:

- **`features/image-generation/`** - Components for image generation UI
- **`features/models/`** - Model management components
- **`features/queue/`** - Job queue and monitoring components

### Forms

Reusable form components:

- **`forms/prompt-textarea.tsx`** - Enhanced text input for prompts

### Layout

Layout and navigation components:

- **`layout/app-layout.tsx`** - Main application layout
- **`layout/header.tsx`** - Application header
- **`layout/sidebar.tsx`** - Navigation sidebar
- **`layout/theme-provider.tsx`** - Theme context provider

### UI

Low-level reusable UI components (shadcn/ui style):

- **`ui/button.tsx`** - Button component
- **`ui/card.tsx`** - Card container
- **`ui/input.tsx`** - Input field
- **`ui/select.tsx`** - Select dropdown
- And more...

## Library Structure

### Hooks

Custom React hooks for common functionality:

```typescript
// hooks/hooks.ts
export function useLocalStorage<T>(key: string, initialValue: T)
export function useAutoSave<T>(key: string, value: T, delay?: number)
```

### Services

External API and business logic services:

```typescript
// services/
export { apiClient } from '../api'
export { AutoModelSelector } from '../auto-model-selector'
```

### Types

TypeScript type definitions and interfaces:

```typescript
// types/
export interface GenerationParams { ... }
export interface ModelDetails { ... }
```

## Import Patterns

### Component Imports

```typescript
// Good: Feature-specific imports
import { ModelStatusBar, EnhancedModelSelect } from '@/components/features';

// Good: Layout imports
import { AppLayout, Header } from '@/components/layout';

// Good: UI imports
import { Button, Card } from '@/components/ui';

// Good: Barrel imports
import { useLocalStorage, apiClient } from '@/lib';
```

### Path Aliases

- `@/` - Root of the webui directory
- `@/components/*` - All component imports
- `@/lib/*` - All library imports
- `@/app/*` - App router pages

## Benefits of This Structure

### 1. Scalability

- Feature-based organization allows teams to work independently
- Clear separation of concerns reduces coupling
- Consistent patterns make onboarding easier

### 2. Maintainability

- Related code is co-located
- Clear naming conventions
- Barrel exports simplify imports

### 3. Reusability

- UI components are generic and reusable
- Hooks abstract common patterns
- Services can be shared across features

### 4. Type Safety

- Centralized type definitions
- Clear interfaces between components
- Consistent TypeScript usage

## Migration Guide

### Moving Components

When adding new components:

1. **UI Components** → `components/ui/`
2. **Feature Components** → `components/features/{domain}/`
3. **Form Components** → `components/forms/`
4. **Layout Components** → `components/layout/`

### Adding Utilities

1. **Hooks** → `lib/hooks/`
2. **Services** → `lib/services/`
3. **Types** → `lib/types/`
4. **Utils** → `lib/utils/`

### Export Patterns

Always export from index files:

```typescript
// components/features/models/index.ts
export { ModelList } from './model-list';
export { ModelStatusBar } from './model-status-bar';
```

## Development Guidelines

### 1. Feature First

Organize by feature, not by file type. All related code for a feature should be together.

### 2. Barrel Exports

Use index.ts files to provide clean import paths and hide implementation details.

### 3. Consistent Naming

- Components: PascalCase
- Files: kebab-case
- Hooks: camelCase with `use` prefix
- Types: PascalCase with descriptive names

### 4. Co-location

Keep related files together:

- Component with its types
- Hook with its tests
- Service with its types

This structure provides a solid foundation for scaling the WebUI application while maintaining code quality and developer productivity.