Architecture Documentation

Durable architecture reference for RustFS: migration guardrails, runtime contracts, boundary rules, and support matrices.

Two rules keep this directory healthy:

1. Durable reference only. One-shot implementation plans, task trackers, and PR templates do not belong in the repository — keep them in the issue tracker or your local worktree. When their work closes, delete them rather than archiving them here.
2. No copies of other sources of truth. Crate lists come from Cargo.toml, CI steps from .github/workflows/ci.yml, code structure from the code. scripts/check_doc_paths.sh fails the pre-commit gate when a doc here references a file path that no longer exists.

Start here

• overview.md — migration baseline, phase order, core principles

CI-enforced core (required by scripts/check_architecture_migration_rules.sh)

• crate-boundaries.md — dependency direction, PR types, re-export contracts
• runtime-lifecycle.md — startup/shutdown sequencing, readiness guarantees
• readiness-matrix.md — request/dependency behavior, probe semantics
• storage-control-data-plane.md — storage API contracts, control-plane boundaries
• global-state-crate-split-plan.md — remaining global-state owners and split evaluation
• ecstore-module-split-plan.md — ECStore decomposition rules and facade contracts

Contracts & invariants

• erasure-coding.md — normative erasure-coding algorithm and on-disk (xl.meta) compatibility contract; the frozen invariants for all user-data read/write, encode/decode, quorum, heal, and decode tolerance
• placement-repair-invariants.md
• unified-object-generation.md — single per-object generation authority (fencing epoch, transport/encoding/proto/mixed-version contracts)
• runtime-capability-contracts.md
• workload-admission-contracts.md
• background-controller-contract.md
• config-model-boundary-adr.md
• ecstore-layout-boundary.md
• decommission-compatibility.md
• kms-bulk-rekey-contract.md — object-side DEK re-wrap job: work unit, idempotency model, exclusion rules, and the never-destroy-old-key-versions constraint

Support matrices (release-facing, keep current)

• s3-compatibility-matrix.md
• s3-tables-support-matrix.md
• minio-rustfs-router-compatibility.md
• minio-file-format-compat.md

Inventories & baselines (snapshots that feed migration work)

• global-state-inventory.md
• ecstore-api-facade-inventory.md
• ecstore-config-consumer-inventory.md
• obs-ecstore-dependency-inventory.md
• background-services-inventory.md
• admin-route-action-snapshot.md
• compat-cleanup-register.md

Historical plans and trackers (rebalance/decommission phases, migration-progress ledger, and the one-shot migration snapshots that fed it — startup timeline, scheduler baseline, profiling/NUMA capability inventory, KMS development defaults inventory) were retired in 2026-07 once the architecture-review ledger they served closed out (backlog#660/#665). Planning documents are no longer kept in the repository.