Dragonfly

# MISSION: Scaffold "Dragonfly" 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 **Dragonfly**.
---
## 1. PROJECT SPECIFICATIONS & BENCHMARK
- **Reference Architecture**: Dragonfly
- **What It Does**: Dragonfly is an in-memory data store implementing the Redis and Memcached wire protocols in C++, built on a custom thread-per-core fiber runtime (Helio) with its own hash-table structures, RDB-compatible snapshotting, and a built-in HNSW vector index.
- **Domain & Category**: Multi-Threaded In-Memory Key-Value Store
- **Production Scale**: 20+ People
- **Development Mode**: CLASSIC
- **Architectural Rationale**: A fiber-based, shared-nothing execution model (one thread and one keyspace shard per core) lets Dragonfly scale vertically across cores, which single-threaded Redis cannot do without external sharding, while staying protocol-compatible so existing clients need no changes.
- **Live Website Reference**: https://dragonflydb.io
- **Source Repository**: https://github.com/dragonflydb/dragonfly
---
## 2. PRODUCTION TECH STACK
- **Full Stack Array**: C++, CMake, Python, Go, Docker, Redis, Memcached protocol
- **Primary Language(s)**: C++, Python, C
- **License of the reference repo**: NOASSERTION
- **Backend & APIs**: C++ — The entire server (src/server, src/core, src/facade) is written in C++, built with CMake and Ninja.; Helio — Dragonfly's in-house fiber-based async I/O and event-loop library that the server's thread-per-core execution model is built on.; src/facade — Implements the Redis and Memcached wire protocols so existing clients work against Dragonfly unmodified.; src/redis — Vendored/adapted Redis-compatible components (command definitions, RDB helpers) reused inside the Dragonfly server.
- **Data & persistence**: In-memory dashtable/dense_set — Dragonfly's custom hash-table structures (docs/dashtable.md, dense_set.md) back key-value storage instead of Redis's own structures.; RDB-compatible snapshotting — Background save produces Redis RDB-format snapshots for persistence and replication bootstrapping.; Async tiering — Optional tiering of colder data out to disk/SSD to extend effective memory capacity beyond RAM.; Vector search (HNSW) — HNSW-based vector index with its own replication protocol for approximate nearest-neighbor search.
- **Infrastructure & deploy**: CMake + Ninja — Primary build system; the Makefile wraps a cmake configure step and a ninja dragonfly build.; Docker — Container images built from contrib/docker for release and dev variants.; Helm chart — contrib/charts/dragonfly packages Dragonfly for Kubernetes deployment.
- **Tooling, testing & ops**: pytest integration suite — Python test suite (tests/dragonfly) exercises the server via redis-py, valkey, and fakeredis clients.; libFuzzer harness — Dedicated fuzzing targets and crash-triage scripts under fuzz/ for the RESP/Memcached parsers.; GitHub Actions — CI covers unit/regression/heavy/epoll-v2 test matrices, fuzzing, benchmarking, and multi-arch Docker releases.
---
## 3. KEY ARCHITECTURAL DECISIONS (audited from https://github.com/dragonflydb/dragonfly @ 4776811)
1. **A custom fiber runtime (Helio) replaces an event-loop library like libuv**: The server is built around helio, an in-repo/vendored C++ fiber and async-I/O library, rather than libuv or Boost.Asio directly, giving Dragonfly a thread-per-core execution model where each core runs its own event loop and shard of the keyspace.
2. **Redis and Memcached compatibility is a protocol-level facade, not a fork**: src/facade implements the RESP and Memcached wire protocols against Dragonfly's own data structures and execution engine in src/core and src/server, so existing Redis/Memcached clients work unmodified without the server being a source fork of either.
3. **Persistence targets the RDB format for drop-in compatibility**: docs/rdbsave.md documents background snapshotting into the Redis RDB format rather than a Dragonfly-specific format, so existing RDB tooling and Redis migration paths keep working.
4. **Custom hash-table structures replace Redis's dict/ziplist internals**: docs/dashtable.md and docs/dense_set.md describe purpose-built data structures for the keyspace, distinct from Redis's own dict implementation, chosen to support the multi-threaded, shard-per-core design.
5. **Vector search ships as a built-in index, not a separate module**: docs/hnsw-index-replication.md and docs/hnsw-replication-serialize.excalidraw describe an HNSW vector index integrated into the core server with its own replication/serialization path, rather than being implemented as a loadable Redis module.
6. **Kubernetes deployment is a first-party Helm chart**: contrib/charts/dragonfly is maintained in-repo with its own Go module (used for chart testing via terratest), rather than leaving Kubernetes packaging entirely to the community.
---
## 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 (In-memory dashtable/dense_set, RDB-compatible snapshotting, Async tiering, Vector search (HNSW)): 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.