Garage

# MISSION: Scaffold "Garage" Production Architecture
You are an expert Senior Staff Software Architect and Full-Stack Engineer. Your mission is to scaffold and implement a production-grade, highly reliable, and modular codebase following the proven architecture of **Garage**.
---
## 1. PROJECT SPECIFICATIONS & BENCHMARK
- **Reference Architecture**: Garage
- **What It Does**: Garage is a self-hosted, S3-compatible distributed object storage system written in Rust, built as a Cargo workspace of crates for small-to-medium geo-distributed clusters that stay available when individual nodes fail.
- **Domain & Category**: Geo-Distributed Object Storage Engine
- **Production Scale**: 2-5 People
- **Development Mode**: CLASSIC
- **Architectural Rationale**: Garage splits RPC, replication, storage and each API protocol into separate Rust crates around a pluggable embedded metadata engine (LMDB, SQLite or Fjall), so a geo-distributed cluster can tolerate node and network failures without depending on an external coordination service or database.
- **Live Website Reference**: https://garagehq.deuxfleurs.fr
- **Source Repository**: https://git.deuxfleurs.fr/Deuxfleurs/garage
---
## 2. PRODUCTION TECH STACK
- **Full Stack Array**: Rust, S3, LMDB, SQLite, Prometheus, Docker, Kubernetes, Nix
- **Primary Language(s)**: Rust
- **License of the reference repo**: AGPL-3.0
- **Backend & APIs**: Rust — Entire cluster (RPC, replication, S3/K2V/admin APIs, web endpoint) is a Cargo workspace of Rust crates under src/.; garage_net — Custom RPC networking layer for inter-node cluster communication, forked from the Netapp project.
- **Data & persistence**: LMDB — Default embedded key-value engine (via the heed crate) backing the metadata tables and cluster state.; SQLite — Alternative embedded metadata engine (via rusqlite/r2d2) selectable instead of LMDB.; Fjall — Newer LSM-based key-value engine offered as a third pluggable metadata backend behind the fjall feature flag.
- **Infrastructure & deploy**: Docker — Runtime image built FROM scratch that just copies the compiled garage binary and runs it as the server.; Nix — flake.nix, default.nix and shell.nix drive reproducible builds and the dev shell; nix/ holds Nix build helpers.; Kubernetes — Optional cluster auto-discovery via the Kubernetes API, gated behind the kubernetes-discovery feature (kube, k8s-openapi crates).; Prometheus — Metrics endpoint exposed through the prometheus and opentelemetry-prometheus crates when the metrics feature is enabled.; Woodpecker CI — Self-hosted CI runs debug, publish and release pipelines instead of GitHub Actions.
- **Tooling, testing & ops**: cargo-fuzz — Nine libFuzzer targets exercise the CRDT types (version, bucket, key, object) for correctness under fuzzing.; Jepsen — script/jepsen.garage drives Jepsen-style distributed-systems correctness testing against a Garage cluster.
---
## 3. KEY ARCHITECTURAL DECISIONS (audited from https://github.com/deuxfleurs-org/garage @ d50be27)
1. **Cluster logic is split into a dozen single-purpose Cargo crates**: The workspace in Cargo.toml lists garage_db, garage_util, garage_net, garage_rpc, garage_table, garage_block, garage_model, garage_api_common/s3/k2v/admin, garage_web and k2v-client as separate members with default-members = ["src/garage"], so the RPC layer, storage-node logic, table replication engine and each API protocol can be developed, versioned and tested independently.
2. **Metadata storage engine is pluggable, not fixed to one database**: src/db/Cargo.toml exposes lmdb, sqlite and fjall as mutually selectable Cargo features implementing a common garage_db trait, so an operator can run Garage on LMDB (default), SQLite, or the newer Fjall LSM engine without changing application code.
3. **Own RPC transport instead of gRPC or plain HTTP for cluster traffic**: src/net/Cargo.toml describes garage_net as "Networking library for Garage RPC communication, forked from Netapp"; inter-node membership, gossip and data-transfer messages run over this custom protocol rather than a generic HTTP or gRPC stack.
4. **K2V is a second, simpler key-value API next to S3**: src/k2v-client/Cargo.toml and src/api/k2v/Cargo.toml implement K2V, described as the "Garage K2V protocol" client and server, giving applications a lighter-weight alternative to the full S3 API for simple key/value access patterns.
5. **Nix is the primary reproducible-build path**: flake.nix, default.nix, shell.nix and the nix/ directory (build_index.nix, compile.nix) provide the release build and dev shell; Cargo.lock alone is not treated as sufficient for reproducibility across the project.
6. **Cluster auto-discovery is optional and pull-based, not required**: src/rpc/Cargo.toml gates Consul and Kubernetes discovery behind the consul-discovery and kubernetes-discovery feature flags (reqwest/hyper for Consul, the kube crate for Kubernetes), so a default build has no dependency on either system and nodes can instead be joined manually.
7. **Distributed correctness is tested with fuzzing and Jepsen, not just unit tests**: fuzz/Cargo.toml defines libFuzzer targets for the CRDT types that back bucket, key and object state (version_crdt, bucket_crdt, object_crdt, key_crdt), and script/jepsen.garage runs Jepsen-style fault-injection tests against a real cluster, reflecting that Garage treats network partitions and node failure as a normal operating condition.
---
## 4. NON-NEGOTIABLE ARCHITECTURAL GUARDRAILS
1. **Monorepo & Modular Separation**:
   - Structure as a Turborepo monorepo with strict package boundaries:
     - `apps/web`: Application UI, routing, layouts, and server endpoints.
     - `packages/ui`: Shared design tokens, CSS variables, and Radix UI primitive components.
     - `packages/db`: Database schemas, client singleton, declarative migrations, and seed scripts.
     - `packages/config`: Shared TypeScript, ESLint, and build configurations.
2. **Strict Type Safety & Zero `any` Policy**:
   - Enable `strict: true`, `noImplicitAny: true`, and `strictNullChecks: true`.
   - Validate ALL external inputs, API request bodies, and query parameters with **Zod** schemas before execution.
3. **Frontend & Rendering Guidelines**:
   - Isolate interactive UI state to leaf components. Keep core pages lightweight and performant.
4. **Design System & Aesthetics**:
   - Keep every color, radius, shadow and font in a single token file (CSS variables) and consume tokens everywhere; never hardcode hex values in components.
   - Prefer crisp 1px borders and one subtle shadow scale over blurry default shadows. Pair one sans-serif for body/headings with one monospace for tags, badges, metrics, and code.
5. **Data Layer & Reliability**:
   - Write declarative schema definitions with foreign keys, composite indexes on queried filters, and automated timestamp triggers.
   - Use connection pooling and prepared statements for serverless database execution.
---
## 5. STEP-BY-STEP SCAFFOLDING ROADMAP
- **Phase 1: Workspace & Root Config**: Initialize package manager, monorepo configuration (`turbo.json`, `tsconfig.base.json`, `package.json`).
- **Phase 2: Database Schema & Client**: Set up the data layer (LMDB, SQLite, Fjall): client, connection pool, models, and migration scripts.
- **Phase 3: Design Tokens & UI Primitives**: Build accessible `Button`, `Input`, `Card`, `Badge`, and layout wrappers inside `packages/ui`.
- **Phase 4: Core Application Routes & Handlers**: Implement primary authentication, user session handling, and application routes.
- **Phase 5: Quality Assurance & Build Verification**: Run `tsc --noEmit`, ESLint, Prettier, and smoke test suites to ensure zero compilation or runtime errors.
---
## 6. EXECUTION INSTRUCTIONS
1. Review all specifications, architectural guardrails, and stack choices above.
2. Present the full monorepo directory tree structure.
3. Systematically generate the complete, production-ready codebase according to the 5-phase roadmap above — starting with the root workspace setup, followed by the database schema, UI design system package, and full-stack application routes until the repository is fully scaffolded and ready to run.