# CLAUDE.md

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

## Project Overview

Simple Object Server is a C++23 application that provides a REST API for storing and retrieving files with metadata. Key features include:
- File storage with deduplication using content hashing
- Metadata management with label:tag system
- Token-based authentication for write operations
- Support for large file uploads
- CORS and rate limiting support

## Common Development Commands

### Building
```bash
# Build for current architecture (debug mode)
./build.sh

# Build for multiple architectures (release mode)
./publish.sh
```

### Testing
```bash
# Build Docker image and run all tests
./test.sh

# Run integration tests directly
./testing/test.sh

# Test large file uploads (1GB)
./testing/test_1GB_file_upload.sh
```

### Development Workflow
1. Make changes to C++ source files in `/src`
2. Run `./build.sh` to compile and check for errors
3. Run `./test.sh` to ensure tests pass
4. Use `./publish.sh` only when ready to create multi-architecture releases

## Architecture and Code Structure

### Key Components

1. **HTTP Server (src/server.cpp/hpp)**
   - Uses httplib for HTTP handling
   - Implements all REST endpoints
   - Handles authentication, CORS, and rate limiting

2. **Database Layer (src/database.cpp/hpp)**
   - SQLite-based metadata storage
   - Stores object hashes, label:tags, and custom metadata as JSON
   - Manages label:tag uniqueness and versioning

3. **Request Handlers**
   - `put_handler.cpp/hpp`: File upload logic with deduplication
   - `update_handler.cpp/hpp`: Metadata update functionality

4. **Utilities**
   - `compression.cpp/hpp`: GZIP compression support
   - `hash.cpp/hpp`: SHA-256 hashing for content deduplication
   - `string_trim.cpp/hpp`: String utility functions

### API Design Patterns

- Files are stored by content hash to enable deduplication
- Label:tag system allows human-friendly naming (e.g., "project:latest")
- When a new file is uploaded with an existing label:tag, the tag is moved to the new file
- All metadata is preserved as JSON, allowing custom fields beyond labeltags

### Build System

- Uses CMake with C++23 standard
- Docker-based build process for consistency across platforms
- Static linking for standalone executables
- Multi-architecture support (linux/amd64, linux/arm64, windows/amd64)

## Testing Approach

The test suite (`testing/test.sh`) covers:
1. File upload and retrieval by hash and label:tag
2. Metadata preservation including custom fields
3. Tag versioning behavior
4. File deletion
5. Rate limiting functionality
6. MD5 checksum verification

Tests use curl for API interactions and jq for JSON parsing.

## Configuration

The server uses JSON configuration (`sos_config.json`) with these key settings:
- `write_tokens`: Array of authentication tokens
- `storage_path`: Where files are stored
- `cors`: CORS policy configuration
- `rate_limiting`: Auth attempt limits

Default configuration is suitable for Docker deployment with storage at `/data/storage`.