stable-diffusion.cpp-rest/webui/STRUCTURE.md

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:

// 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:

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

Types

TypeScript type definitions and interfaces:

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

Import Patterns

Component Imports

// 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:

// 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.