offline-web/CLAUDE.md

CLAUDE.md

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

Architecture Overview

This is an offline-first web application framework built in Rust with dual native/WASM compilation support. The architecture consists of:

Core Crates

• offline-web-model: Content-addressable graph data structures with Reference types that form a DAG (Directed Acyclic Graph). References contain object IDs, content addresses, names, and dependents. The graph automatically recalculates IDs when content changes to maintain content addressability.
• offline-web-storage: Storage abstraction layer with ReferenceStore trait. Includes SQLite implementation for native builds and IndexedDB for WASM. Uses feature flags to conditionally compile storage backends.
• exp1 & exp2: Experimental server implementations demonstrating the framework

Data Model

The framework uses a content-addressable system where:

• All resources form a merkle tree structure
• Resource reference paths are rooted at /ref/ prefix
• Content-addressable paths are rooted at /object/<content-hash>
• Reserved references include /ref/all/<username> (user's root) and /ref/user/<username> (user info)

Build Commands

• Build all crates for both native and wasm: make build
• Build crates for native: make native
• Build crates for wasm: make wasm
• Build individual crates: make model-native, make storage-native, make model-wasm, make storage-wasm

Testing

• Unit tests: cargo test (for native features)
• Model tests: cargo test -p offline-web-model --features native
• Storage integration tests: cargo test -p offline-web-storage --features native
• WASM builds require --target=wasm32-unknown-unknown and --features wasm

Feature Flags

Both core crates use conditional compilation:

• native: Enables SQLite, tokio, full native functionality
• wasm: Enables WASM-specific dependencies (getrandom/wasm_js, uuid/js, wasm-bindgen)

Code Style Guidelines

Formatting & Imports

• Group imports by std, external crates, and internal modules
• Sort imports alphabetically within groups
• Use block imports with curly braces for multi-imports

Types & Naming

• Use snake_case for functions, variables, and modules
• Use PascalCase for types and structs
• Prefix trait implementations with the trait name
• Use Option for nullable values, not unwrap()

Error Handling

• Use Result<T, E> with custom error types
• Implement thiserror::Error for error enums
• Propagate errors with ? operator
• Use descriptive error messages

Documentation

• Document public APIs with /// comments
• Include examples in documentation for complex functions
• Explain parameter and return types in function docs