stable-diffusion.cpp-rest/CRUSH.md

CRUSH.md - Agent Guide for stable-diffusion.cpp-rest

This document contains essential information for agents working with the stable-diffusion.cpp-rest codebase.

Project Overview

This is a C++ REST API server that wraps the stable-diffusion.cpp library, providing HTTP endpoints for image generation with Stable Diffusion models. The project includes both a C++ backend and a Next.js frontend (webui).

Build Commands

Main Build Process

# Create build directory and configure
mkdir build && cd build
cmake ..

# Build everything (including web UI)
cmake --build . -j4

# Alternative: Use the existing rule file command
cd build
cmake --build . -j4

Web UI Only

cd webui
npm install
npm run build

Testing

# Run model detection tests
./test_model_detection.sh

# Test compilation of specific components
g++ -std=c++17 -I./include -I. -c src/model_detector.cpp -o test_compile.o

Project Structure

C++ Backend

• src/ - Source files (.cpp)
• include/ - Header files (.h)
• CMakeLists.txt - Main build configuration
• .clang-format - C++ formatting rules (Chromium-based, 4-space indent)

Web Frontend

• webui/ - Next.js React application
• webui/package.json - Node.js dependencies
• webui/tsconfig.json - TypeScript configuration
• webui/next.config.ts - Next.js config (static export with /ui basePath)

Model Organization

Models are stored in /data/SD_MODELS/ (not in project root to keep directory clean). Supported model types include:

• CHECKPOINT (.safetensors, .pt, .ckpt)
• LORA models
• VAE models
• Various other types (embeddings, upscalers, etc.)

Code Standards and Conventions

C++ Standards

• C++17 standard
• NO using aliases - Never use using json = nlohmann::json;
• Follow Rule of 5 for class design
• Use absolute paths when printing directory/file names to console
• 4-space indentation (configured in .clang-format)

TypeScript/React Standards

• TypeScript with strict mode enabled
• Next.js 16 with React 19
• Tailwind CSS for styling
• ESLint with Next.js configuration
• Path aliases: @/* maps to webui root

Key Architecture Patterns

Model Detection System

The project uses intelligent model detection in src/model_detector.cpp:

• Detects architecture: SD 1.5, SD 2.1, SDXL, Flux, SD3, Qwen2VL
• Traditional models → ctxParams.model_path
• Modern architectures → ctxParams.diffusion_model_path
• Unknown architectures fallback to traditional loading

Three-Tier Architecture

1. HTTP Server - Request parsing, response formatting
2. Generation Queue - Sequential job processing, thread-safe
3. Model Manager - Model loading, architecture detection, memory management

Authentication System

Multiple authentication methods supported:

• none - No authentication (default)
• jwt - JWT token authentication
• api-key - Static API keys
• unix - Unix system authentication
• pam - PAM authentication (requires libpam0g-dev)
• optional - Authentication optional

Testing Approach

Model Detection Testing

Use the provided test script:

./test_model_detection.sh

This tests:

• Architecture detection logic
• Path selection rules
• Error handling
• Integration points
• Available model files
• Compilation status

Server Testing

• Start server in background during testing
• Use browser MCP tools for webui testing
• Test with actual model files in /data/SD_MODELS/

Important Gotchas

Build System

• Keep build/_deps folder - Rebuilding dependencies takes very long time
• Web UI automatically builds with main project via CMake
• CMake automatically downloads and builds stable-diffusion.cpp as external project

Path Management

• Always use absolute paths when printing to console
• Models directory: /data/SD_MODELS/ (not project root)
• UI directory when starting server: --ui-dir ./build/webui
• Keep project directory clean - no output/queue directories in root

Web UI Configuration

• Next.js configured for static export (output: 'export')
• Base path: /ui
• Asset prefix: /ui
• No image optimization (unoptimized: true)

Development Workflow

1. Code Changes: Make changes to C++ or TypeScript files
2. Build: Run cmake --build . -j4 from build directory
3. Test: Use appropriate test methods (shell scripts, browser tools)
4. Web UI Updates: If changing webui, the build process includes it
5. Commit: Always commit and push changes, reference related issues

MCP Tools Integration

• Always use available MCP tools for speeding up tasks
• Browser MCP tools for webui testing
• Gogs MCP tools for repository issue management

Configuration Files

• .clang-format - C++ code formatting
• .clang-tidy - C++ static analysis
• webui/tsconfig.json - TypeScript configuration
• webui/eslint.config.mjs - ESLint configuration
• webui/next.config.ts - Next.js build configuration

Dependencies

C++ Dependencies

• stable-diffusion.cpp (auto-downloaded by CMake)
• CUDA Toolkit (optional, for GPU acceleration)
• PAM libraries (optional, for PAM auth)

Web UI Dependencies

• Node.js and npm
• Next.js 16
• React 19
• Tailwind CSS 4
• Radix UI components

Model File Formats

The project supports various model quantization levels:

• f32, f16 - Floating point formats
• q8_0, q4_0, q3_k - Quantized formats
• GGUF format for converted models
• Original .safetensors and .ckpt formats

Remember: This project serves as a bridge between the C++ stable-diffusion.cpp library and web applications, with emphasis on performance, security, and ease of use.