rhizome-node/CLAUDE.md

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 and the specifications in 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.

Development Commands

# 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:*