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: `make test` (for native features)
- Model tests: `make test-model`
- Storage integrations tests: `make test-storage-native test-storage-wasm`
- Cargo 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<T> 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