AgentSkillsCN

architecture

加载ECSdb架构规划与关键设计决策

SKILL.md
--- frontmatter
name: architecture
description: Load the ECSdb architecture plan and key design decisions
allowed-tools: Read, Glob
model: haiku

ECSdb Architecture Reference

Load the architecture context for implementation decisions.

Core Architecture Documents

Read and summarize the following:

  1. •

    Sprint Tracker Overview: sprints/SPRINT_TRACKER.md

    • •Milestone definitions
    • •Critical path
    • •Architectural revision notices
  2. •

    Sprint 02 - Storage Core: sprints/sprint-02-storage-core/README.md

    • •Storage engine design (fjall-based)
    • •ComponentData vs JSONB decision
    • •Column family architecture
  3. •

    Key Ticket Specifications (read these for design patterns):

    • •sprints/sprint-02-storage-core/TICKET-02-004.md (ComponentData)
    • •sprints/sprint-02-storage-core/TICKET-02-005.md (StorageEngine trait)
    • •sprints/sprint-02-storage-core/TICKET-02-011.md (fjall adapter)
    • •sprints/sprint-02-storage-core/TICKET-02-012.md (Column family manager)

Output: Architecture Summary

code
# ECSdb Architecture Reference

## Storage Engine
- **Backend**: fjall (pure Rust LSM-tree)
- **Organization**: Column families per component type
- **Key reserved CFs**: _metadata, _edges, _schemas, _constraints, _bitmap_index

## Data Model
- **Entity**: Metadata only (no state blob)
- **ComponentData**: Per-component storage with versioning
- **Key format**: [entity_id:16][version:8]
- **Serialization**: MessagePack (rmp-serde)

## Key Traits
- `StorageEngine`: Abstract over fjall
- `SchemaRegistry`: Component schema validation
- `ConstraintManager`: Uniqueness enforcement

## Column Family Layout

_metadata → Entity records _edges → Relationship edges _schemas → Component schemas _constraints → Uniqueness constraints bitmap_index → RoaringBitmap component membership component<Name> → Per-component data

code

## MVCC Design
- `xmin`: Transaction that created record
- `xmax`: Transaction that deleted record (0 if live)
- Visibility rules follow PostgreSQL semantics

## Query Flow

JSON Query → AST → Logical Plan → Optimized Plan → Execution → Streaming Results

code

## Key Dependencies
| Crate | Purpose | Version |
|-------|---------|---------|
| fjall | Storage | 1.0+ |
| roaring | Bitmaps | latest |
| rmp-serde | Serialization | 1.0+ |
| tonic | gRPC | latest |

## Design Principles
1. Component storage is per-type (not per-entity blob)
2. fjall handles WAL, memtable, sstable, compaction
3. We build MVCC and query layers on top
4. Schema registry is source of truth for components