61 lines
2.7 KiB
Markdown
61 lines
2.7 KiB
Markdown
|
# 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<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
|