89 lines
2.9 KiB
Markdown
89 lines
2.9 KiB
Markdown
# CLAUDE.md
|
|
|
|
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. Work on this project should follow the priorities defined in [todo.md](todo.md) and the specifications in [spec.md](spec.md).
|
|
|
|
## Project Overview
|
|
|
|
Rhizome-node is a distributed, peer-to-peer database engine that implements a rhizomatic (decentralized, non-hierarchical) data model. It synchronizes data across multiple nodes without a central authority using immutable "deltas" as the fundamental unit of change. There is a specification for the behavior of this system in [spec.md](spec.md).
|
|
|
|
## Development Commands
|
|
|
|
```bash
|
|
# Build the TypeScript project
|
|
npm run build
|
|
|
|
# Build in watch mode
|
|
npm run build:watch
|
|
|
|
# Run tests
|
|
npm test
|
|
|
|
# Run a specific test file
|
|
npm test -- __tests__/delta.ts
|
|
|
|
# Run linter
|
|
npm run lint
|
|
|
|
# Generate coverage report
|
|
npm run coverage
|
|
|
|
# Run the example application
|
|
npm run example-app
|
|
```
|
|
|
|
## Architecture Overview
|
|
|
|
### Core Concepts
|
|
|
|
1. **Deltas**: Immutable change records that describe modifications to entities. Each delta contains:
|
|
- Unique ID and timestamps
|
|
- Creator and host information
|
|
- Pointers defining entity/property relationships
|
|
- DeltaV2 is the current format (DeltaV1 is legacy)
|
|
|
|
2. **Views**: Different ways to interpret the delta stream:
|
|
- **Lossless View**: Stores all deltas without conflict resolution
|
|
- **Lossy Views**: Apply conflict resolution (e.g., Last-Write-Wins)
|
|
- Custom resolvers can be implemented
|
|
|
|
3. **Collections**: Group related entities (similar to database tables)
|
|
- Support typed collections via `TypedCollection<T>`
|
|
- Implement CRUD operations through delta generation
|
|
|
|
4. **Networking**: Dual transport layer:
|
|
- ZeroMQ for efficient binary communication
|
|
- libp2p for decentralized peer discovery
|
|
- Pub/sub for delta propagation
|
|
- Request/reply for synchronization
|
|
|
|
### Key Files and Entry Points
|
|
|
|
- `src/node.ts`: Main `RhizomeNode` class orchestrating all components
|
|
- `src/delta.ts`: Delta data structures and conversion logic
|
|
- `src/lossless.ts`: Core lossless view implementation
|
|
- `src/collection-basic.ts`: Basic collection implementation
|
|
- `src/http/api.ts`: REST API endpoints
|
|
- `src/pub-sub.ts`: Network communication layer
|
|
|
|
### Testing Patterns
|
|
|
|
- Unit tests in `__tests__/` directory
|
|
- Multi-node integration tests in `__tests__/run/`
|
|
- Use Jest with experimental VM modules
|
|
- Test files follow pattern: `{feature}.ts`
|
|
|
|
### HTTP API Structure
|
|
|
|
The HTTP API provides RESTful endpoints:
|
|
- `GET/PUT /collection/:name/:id` - Entity operations
|
|
- `GET /peers` - Peer information
|
|
- `GET /deltas/stats` - Delta statistics
|
|
- `GET /lossless/:entityId` - Raw delta access
|
|
|
|
### Important Implementation Notes
|
|
|
|
- All data modifications go through deltas - never modify state directly
|
|
- Deltas are immutable once created
|
|
- Use `Context.getOrCreate()` for singleton access
|
|
- Network ports: publish (default 4000) and request (default 4001)
|
|
- Debug logging uses namespaces like `rhizome:*` |