RustFS Architecture Evolution

This document set tracks the architecture migration from rustfs/backlog#660.

Baseline

Baseline branch: upstream/main
Baseline commit: 61f0dfbc40f748be313be84d834d8259cf3e19c9
Baseline title: fix(ecstore): invalidate wiped disk id cache (#3251)
First migration PR type: docs-only

Core Principle

Cut wrong dependency directions with directories and contracts first, migrate global state in small steps next, and split crates only after boundaries are stable. Storage hot-path behavior must not drift during this migration.

Architecture Documents

runtime-lifecycle.md: runtime, AppContext, startup/readiness, and shutdown contracts.
storage-control-data-plane.md: boundaries between StorageCore, ECStore, ClusterControlPlane, and BackgroundControllers.
crate-boundaries.md: PR types, crate direction, compatibility rules, and migration guardrails.
ecstore-config-consumer-inventory.md: current ecstore::config::{Config, KV, KVS} definitions, consumers, migration risks, and do-not-change contract.
migration-progress.md: current task state and context handoff.
compat-cleanup-register.md: temporary compatibility code that must be removed later.

Phase Order

mermaid

flowchart LR
    G["Phase 0: Baseline and guardrails"]
    CFG["Phase 1a: Config model contract"]
    SEC["Phase 1: Security governance"]
    API["Phase 2: Storage API contracts"]
    RT["Phase 3: Runtime and lifecycle"]
    EC["Phase 4: ECStore internal layout"]
    CP["Phase 5: Cluster control plane"]
    EXT["Phase 6: Extension plane"]
    GS["Phase 7: Global-state reduction"]
    CR["Crate split evaluation"]

    G --> CFG
    G --> SEC
    G --> API
    G --> RT
    CFG --> EXT
    API --> EC
    RT --> GS
    EC --> CP
    EXT --> CR
    GS --> CR

The first implementation sequence is conservative:

Record baseline and migration context.
Establish PR and compatibility rules.
Add dependency and loss-prevention checks in a separate ci-gate PR.
Inventory ecstore::config::{Config, KV, KVS} before moving any code.