photoncloud-monorepo/flaredb/specs/001-distributed-core/plan.md

Implementation Plan: Core Distributed Architecture (Phase 1)

Branch: 001-distributed-core | Date: 2025-11-30 | Spec: specs/001-distributed-core/spec.md Input: Feature specification from /specs/001-distributed-core/spec.md

Note: This template is filled in by the /speckit.plan command. See .specify/templates/commands/plan.md for the execution workflow.

Summary

Implement the foundational architecture for FlareDB, a distributed key-value store with CAS support. This includes setting up a Rust Cargo Workspace with 5 crates (rdb-proto, rdb-storage, rdb-server, rdb-pd, rdb-client), defining gRPC interfaces, implementing a RocksDB-based local storage engine, and verifying basic client-server interaction.

Technical Context

Language/Version: Rust (Latest Stable) Primary Dependencies:

• tonic (gRPC)
• prost (Protobuf)
• rocksdb (Storage Engine)
• tokio (Async Runtime)
• clap (CLI) Storage: RocksDB (embedded via crate) Testing: cargo test (Unit), cargo nextest (Optional), Custom Integration Scripts Target Platform: Linux (x86_64), managed via Nix Flake Project Type: Rust Cargo Workspace (Monorepo) with Nix environment Performance Goals: Low-latency CAS operations (local storage baseline) Constraints: Single-node verification for Phase 1, but architecture must support distributed extension. Scale/Scope: 5 crates, ~2000 LOC estimate.

Constitution Check

GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.

• I. Reliability & Testing:
  • Plan includes unit tests for rdb-storage (SC-002).
  • Plan includes integration verification (SC-003).
  • Compliant.
• II. Agility & Evolution:
  • Architecture uses standard crates (tonic, rocksdb) to avoid reinventing wheels.
  • Monorepo structure allows easy refactoring across crates.
  • Compliant.
• III. Simplicity & Readability:
  • Separation of concerns: Proto vs Storage vs Server vs PD vs Client.
  • Clear interfaces defined in rdb-proto.
  • Compliant.

Project Structure

Documentation (this feature)

specs/001-distributed-core/
├── plan.md              # This file (/speckit.plan command output)
├── research.md          # Phase 0 output (/speckit.plan command)
├── data-model.md        # Phase 1 output (/speckit.plan command)
├── quickstart.md        # Phase 1 output (/speckit.plan command)
├── contracts/           # Phase 1 output (/speckit.plan command)
└── tasks.md             # Phase 2 output (/speckit.tasks command - NOT created by /speckit.plan)

Source Code (repository root)

flake.nix                 # Nix development environment definition
flake.lock                # Lockfile for Nix dependencies
Cargo.toml                # Workspace definition
rdb-proto/
├── Cargo.toml
├── build.rs
└── src/                  # Generated protos
rdb-storage/
├── Cargo.toml
└── src/                  # RocksDB wrapper, CAS logic
rdb-server/
├── Cargo.toml
└── src/                  # gRPC Server, Handlers
rdb-pd/
├── Cargo.toml
└── src/                  # Placement Driver (TSO)
rdb-client/
├── Cargo.toml
└── src/                  # Smart SDK
rdb-cli/                  # (Optional for Phase 1, but good to have)
├── Cargo.toml
└── src/

Structure Decision: Standard Rust Workspace layout to ensure modularity and separation of concerns as per the architecture design.

Complexity Tracking

Fill ONLY if Constitution Check has violations that must be justified

Violation	Why Needed	Simpler Alternative Rejected Because
N/A