CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

SIPI (Simple Image Presentation Interface) is a multithreaded, high-performance, IIIF-compatible media server written in C++23. It implements IIIF Image API 3.0 and provides efficient image format conversions while preserving metadata. The server can be used both as a command-line tool and as a web server with Lua scripting support.

Build System and Common Commands

Docker-based Development (Recommended)

# Compile SIPI with debug symbols
make compile

# Run tests
make test

# Build and run server
make run

# Build Docker image
make docker-build

# Run smoke tests
make test-smoke

Native Development (with Nix)

# Enter Nix development shell
nix develop .#clang    # or `just clang`
nix develop           # gcc environment, or `just gcc`

# Build project
just build            # or cmake -B build -S . -DCMAKE_BUILD_TYPE=Debug
cmake --build ./build --parallel

# Run tests
just test             # or cd build && ctest --output-on-failure

# Generate test coverage
just coverage         # uses gcovr
just coverage1        # uses lcov with HTML output

# Run SIPI server
just run              # or ./build/sipi --config=config/sipi.config.lua

# Run with Valgrind
just valgrind

macOS Development (Not Recommended)

mkdir -p ./build-mac && cd build-mac && cmake .. && make && ctest --verbose

Documentation

# Build documentation
make docs-build

# Serve documentation locally
make docs-serve

# Serve doxygen docs (after building via cmake)
just doxygen-serve

High-Level Architecture

Core Components

Main Application (

src/sipi.cpp

)

Entry point supporting both command-line and server modes
Uses CLI11 for argument parsing
Integrates with Sentry for error reporting
Handles global library initialization

SipiImage (

src/SipiImage.hpp

)

Primary image processing class handling all image operations
Supports TIFF, JPEG2000, PNG, JPEG formats
Manages pixel data, metadata (EXIF, IPTC, XMP), and ICC color profiles
Provides scaling, rotation, cropping, color space conversion

SipiHttpServer (

src/SipiHttpServer.hpp

)

Main HTTP server extending shttps::Server framework
Manages IIIF API endpoints and image serving
Handles caching, quality settings, and compression
Integrates with Lua scripting for custom request handling

IIIF Implementation (

include/iiifparser/

)

Complete IIIF 2.0 URL parsing with components:
- ```
SipiIdentifier.h
```
  - Image identifier handling
- ```
SipiRegion.h
```
  - Region of interest parsing
- ```
SipiSize.h
```
  - Size parameter handling
- ```
SipiRotation.h
```
  - Rotation parameter parsing
- ```
SipiQualityFormat.h
```
  - Quality and format parsing

Format Handlers (

include/formats/

)

Abstract base class SipiIO for image I/O operations
Concrete implementations: SipiIOTiff, SipiIOJ2k, SipiIOJpeg, SipiIOPng
Handles reading/writing with region selection and scaling

SHTTPS Framework (

shttps/

)

Custom HTTP server implementation with multi-threading
SSL/TLS support, connection pooling, keep-alive
Lua script integration for custom routes
JWT authentication support

Caching System (

include/SipiCache.h

)

Intelligent file-based caching with size-based limits
LRU eviction policies and concurrent access protection
Canonical URL-based cache keys

Lua Integration (

include/SipiLua.h

)

Lua bindings for SipiImage manipulation
Custom functions for image processing, database access, HTTP handling
Configuration and route handlers via Lua scripts

Image Processing Pipeline

Request Reception: HTTP server receives IIIF URL
URL Parsing: IIIF parameters extracted and validated
Cache Check: SipiCache checks for existing processed image
Image Loading: SipiImage loads original via appropriate SipiIO handler
Processing: Apply region selection, scaling, rotation, quality adjustments
Output: Serve processed image or write to cache

Configuration

Main config:
```
config/sipi.config.lua
```
Test config:
```
config/sipi.test-config.lua
```
Debug config:
```
config/sipi.debug-config.lua
```
Lua scripts in
```
scripts/
```
directory for custom functionality

Testing Structure

Unit Tests (

test/unit/

)

GoogleTest framework with ApprovalTests
Tests for configuration, iiifparser, sipiimage, logger, handlers

Run specific test:

cd build && test/unit/[component]/[component]

End-to-End Tests (

test/e2e/

)

Python pytest-based tests
Run with:
```
pytest -s --sipi-exec=./build/sipi
```
(from test/e2e/)

Approval Tests (

test/approval/

)

Snapshot-based testing for regression detection

Smoke Tests (

test/smoke/

)

Tests against Docker images
Run with:
```
pytest -s test/smoke
```

Dependencies

External Libraries (built from source in

ext/

)

Image formats: libtiff, libpng, libjpeg, libwebp
Compression: zlib, bzip2, xz, zstd
JPEG2000: kakadu (requires license)
Metadata: exiv2, lcms2 (color profiles)
Lua: lua + luarocks
JSON: jansson
Database: sqlite3
Error reporting: sentry

System Dependencies

OpenSSL, libcurl, libmagic (via pkg-config)
Threads (pthread)
iconv (macOS)

Important Files

```
CMakeLists.txt
```
- Main build configuration
```
Makefile
```
- Docker-based build targets
```
justfile
```
- Nix-based development commands
```
version.txt
```
- Version information
```
vars.mk
```
- Build variables
```
flake.nix
```
- Nix development environment

Development Notes

Compiler Requirements

C++23 standard required
Clang ≥ 15.0 or GCC ≥ 13.0
CMake ≥ 3.28

Build Types

Debug:
```
-O0 -g
```
with debug symbols
Release:
```
-O3 -DNDEBUG
```
optimized
RelWithDebInfo:
```
-O3 -g
```
optimized with debug symbols

Commit Message Format Uses Conventional Commits with prefixes:

feat:

fix:

docs:

style:

refactor:

test:

chore:

Error Reporting Optional Sentry integration via environment variables:

```
SIPI_SENTRY_DSN
```
- Sentry project DSN
```
SIPI_SENTRY_ENVIRONMENT
```
- Environment name
```
SIPI_SENTRY_RELEASE
```
- Release version

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

# Compile SIPI with debug symbols
make compile

# Run tests
make test

# Build and run server
make run

# Build Docker image
make docker-build

# Run smoke tests
make test-smoke

Native Development (with Nix)

# Enter Nix development shell
nix develop .#clang    # or `just clang`
nix develop           # gcc environment, or `just gcc`

# Build project
just build            # or cmake -B build -S . -DCMAKE_BUILD_TYPE=Debug
cmake --build ./build --parallel

# Run tests
just test             # or cd build && ctest --output-on-failure

# Generate test coverage
just coverage         # uses gcovr
just coverage1        # uses lcov with HTML output

# Run SIPI server
just run              # or ./build/sipi --config=config/sipi.config.lua

# Run with Valgrind
just valgrind

macOS Development (Not Recommended)

mkdir -p ./build-mac && cd build-mac && cmake .. && make && ctest --verbose

Documentation

# Build documentation
make docs-build

# Serve documentation locally
make docs-serve

# Serve doxygen docs (after building via cmake)
just doxygen-serve

High-Level Architecture

Core Components

Main Application (

src/sipi.cpp

)

Entry point supporting both command-line and server modes
Uses CLI11 for argument parsing
Integrates with Sentry for error reporting
Handles global library initialization

SipiImage (

src/SipiImage.hpp

)

Primary image processing class handling all image operations
Supports TIFF, JPEG2000, PNG, JPEG formats
Manages pixel data, metadata (EXIF, IPTC, XMP), and ICC color profiles
Provides scaling, rotation, cropping, color space conversion

SipiHttpServer (

src/SipiHttpServer.hpp

)

Main HTTP server extending shttps::Server framework
Manages IIIF API endpoints and image serving
Handles caching, quality settings, and compression
Integrates with Lua scripting for custom request handling

IIIF Implementation (

include/iiifparser/

)

Complete IIIF 2.0 URL parsing with components:
- ```
SipiIdentifier.h
```
  - Image identifier handling
- ```
SipiRegion.h
```
  - Region of interest parsing
- ```
SipiSize.h
```
  - Size parameter handling
- ```
SipiRotation.h
```
  - Rotation parameter parsing
- ```
SipiQualityFormat.h
```
  - Quality and format parsing

Format Handlers (

include/formats/

)

Abstract base class SipiIO for image I/O operations
Concrete implementations: SipiIOTiff, SipiIOJ2k, SipiIOJpeg, SipiIOPng
Handles reading/writing with region selection and scaling

SHTTPS Framework (

shttps/

)

Custom HTTP server implementation with multi-threading
SSL/TLS support, connection pooling, keep-alive
Lua script integration for custom routes
JWT authentication support

Caching System (

include/SipiCache.h

)

Intelligent file-based caching with size-based limits
LRU eviction policies and concurrent access protection
Canonical URL-based cache keys

Lua Integration (

include/SipiLua.h

)

Lua bindings for SipiImage manipulation
Custom functions for image processing, database access, HTTP handling
Configuration and route handlers via Lua scripts

Image Processing Pipeline

Request Reception: HTTP server receives IIIF URL
URL Parsing: IIIF parameters extracted and validated
Cache Check: SipiCache checks for existing processed image
Image Loading: SipiImage loads original via appropriate SipiIO handler
Processing: Apply region selection, scaling, rotation, quality adjustments
Output: Serve processed image or write to cache

Configuration

Main config:
```
config/sipi.config.lua
```
Test config:
```
config/sipi.test-config.lua
```
Debug config:
```
config/sipi.debug-config.lua
```
Lua scripts in
```
scripts/
```
directory for custom functionality

Testing Structure

Unit Tests (

test/unit/

)

GoogleTest framework with ApprovalTests
Tests for configuration, iiifparser, sipiimage, logger, handlers

Run specific test:

cd build && test/unit/[component]/[component]

End-to-End Tests (

test/e2e/

)

Python pytest-based tests
Run with:
```
pytest -s --sipi-exec=./build/sipi
```
(from test/e2e/)

Approval Tests (

test/approval/

)

Snapshot-based testing for regression detection

Smoke Tests (

test/smoke/

)

Tests against Docker images
Run with:
```
pytest -s test/smoke
```

Dependencies

External Libraries (built from source in

ext/

)

Image formats: libtiff, libpng, libjpeg, libwebp
Compression: zlib, bzip2, xz, zstd
JPEG2000: kakadu (requires license)
Metadata: exiv2, lcms2 (color profiles)
Lua: lua + luarocks
JSON: jansson
Database: sqlite3
Error reporting: sentry

System Dependencies

OpenSSL, libcurl, libmagic (via pkg-config)
Threads (pthread)
iconv (macOS)

Important Files

```
CMakeLists.txt
```
- Main build configuration
```
Makefile
```
- Docker-based build targets
```
justfile
```
- Nix-based development commands
```
version.txt
```
- Version information
```
vars.mk
```
- Build variables
```
flake.nix
```
- Nix development environment

Development Notes

Compiler Requirements

C++23 standard required
Clang ≥ 15.0 or GCC ≥ 13.0
CMake ≥ 3.28

Build Types

Debug:
```
-O0 -g
```
with debug symbols
Release:
```
-O3 -DNDEBUG
```
optimized
RelWithDebInfo:
```
-O3 -g
```
optimized with debug symbols

Commit Message Format Uses Conventional Commits with prefixes:

feat:

fix:

docs:

style:

refactor:

test:

chore:

Error Reporting Optional Sentry integration via environment variables:

```
SIPI_SENTRY_DSN
```
- Sentry project DSN
```
SIPI_SENTRY_ENVIRONMENT
```
- Environment name
```
SIPI_SENTRY_RELEASE
```
- Release version

CLAUDE.md

CLAUDE.md

Project Overview

Build System and Common Commands

Docker-based Development (Recommended)

Native Development (with Nix)

macOS Development (Not Recommended)

Documentation

High-Level Architecture

Core Components

Image Processing Pipeline

Configuration

Testing Structure

Dependencies

Important Files

Development Notes

Related Skills

Markdown Converter

Nano Banana Pro

1password

CLAUDE.md

Project Overview

Build System and Common Commands

Docker-based Development (Recommended)

Native Development (with Nix)

macOS Development (Not Recommended)

Documentation

High-Level Architecture

Core Components

Image Processing Pipeline

Configuration

Testing Structure

Dependencies

Important Files

Development Notes