# codecrafters-io/build-your-own-redis architecture

> Architecture diagram of the GitHub repository codecrafters-io/build-your-own-redis, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-17). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/codecrafters-io/build-your-own-redis
- Repository: https://github.com/codecrafters-io/build-your-own-redis

## Overview

This repository is not an application runtime; it is the content and scaffolding source for Codecrafters’ “Build your own Redis” course.

1. **Top-level orchestration**
   - `course-definition.yml` is the main course specification entrypoint.
   - `stage_descriptions/` contains the human-readable stage docs for each Redis feature area.
   - Together these define the progression of the challenge and what each stage teaches.

2. **Stage model**
   - The stage files are organized by capability area: `base`, `auth`, `lists`, `sorted-sets`, `streams`, `transactions`, `replication`, `persistence-rdb`, `pub-sub`, `geospatial`, `optimistic-locking`, and `aof`.
   - That structure tells you the course is a stepwise Redis implementation, likely with increasingly sophisticated server behavior and data handling.

3. **Starter template subsystem**
   - `starter_templates/` contains the source templates for each supported language.
   - Each template is a minimal Redis server skeleton with the language-specific build files and a single entrypoint file.
   - These templates are the canonical inputs for generating new learner repositories.

4. **Language support boundaries**
   - The repo supports many runtimes: C, C++, C#, Clojure, Crystal, Dart, Elixir, Gleam, Go, Haskell, Java, JavaScript/Node, Kotlin, OCaml, Odin, PHP, Python, Ruby, Rust, Scala, Swift, and Zig.
   - Each language folder is isolated, with its own build metadata and startup conventions.

5. **Runtime/build abstraction**
   - Every starter includes `.codecrafters/compile.sh` and `.codecrafters/run.sh`.
   - These scripts standardize how Codecrafters builds and runs the program regardless of language.
   - This is the key portability boundary: the course runner talks to these scripts, not directly to the language toolchain.

6. **Compiled starter artifacts**
   - `compiled_starters/` mirrors the starter templates, but in a “ready-to-run” compiled form.
   - This suggests a generated/distributed artifact layer used by the platform for faster setup or validation.
   - In architecture terms, it is the packaged output of the starter-template pipeline.

7. **Solution snapshots**
   - `solutions/` contains completed implementations for each language and multiple solution revisions (`01-jm1`, `02-rg2`, `03-wy1`).
   - Each solution is paired with a `diff/` folder showing the change from the previous state.
   - This makes the repo useful for progression review, benchmarking, or reconstructing how a solution evolves through stages.

8. **Per-solution configuration**
   - Some solution folders include `config.yml`, which appears to carry solution-stage metadata.
   - The code directories under `solutions/.../code/` are structurally aligned with the starter templates, reinforcing that solutions are generated or transformed variants of the same base project shape.

9. **Language-specific build systems**
   - The build tooling is native to each ecosystem: CMake/vcpkg, Maven, Gradle, Cargo, Go modules, Mix, Stack, Dune, Swift Package Manager, Bun/Node, Python `pyproject`, etc.
   - These build files are not just incidental; they define how the challenge is compiled, run, and validated in each language.

10. **Dockerized toolchain matrix**
   - `dockerfiles/` contains versioned images for every supported language/runtime.
   - This is the infrastructure layer that keeps builds reproducible across many language versions and platform variants.
   - The architecture is therefore “course content + language-runtime containers,” not a single deployable service.

11. **Automation and validation**
   - `.github/workflows/test.yml` provides CI validation.
   - In this repo type, CI usually checks template integrity, generated assets, or consistency across languages and stages rather than unit tests for a single codebase.

12. **How the pieces fit together**
   - Course definition and stage descriptions define the learning path.
   - Starter templates provide the per-language starting point.
   - Codecrafters scripts plus Dockerfiles make execution uniform across languages.
   - Compiled starters and solution snapshots are the generated/distributed artifacts used by the platform and maintainers.

13. **Diagram takeaway**
   - If you’re drawing this repository, model it as a content pipeline:
     - course/stage definitions → language starter templates → generated compiled starters / learner repos
     - and parallel solution snapshots + diffs for maintainers.
   - The main “systems” here are authoring content, generating language-specific scaffolds, and validating them in CI/containerized environments.

Main entry points: [`starter_templates`](https://github.com/codecrafters-io/build-your-own-redis/tree/main/starter_templates) (Starter templates), [`compiled_starters`](https://github.com/codecrafters-io/build-your-own-redis/tree/main/compiled_starters) (Compiled starters), [`.github/workflows/test.yml`](https://github.com/codecrafters-io/build-your-own-redis/blob/main/.github/workflows/test.yml) (CI check), [`course-definition.yml`](https://github.com/codecrafters-io/build-your-own-redis/blob/main/course-definition.yml) (Course spec)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_authoring["Authoring"]
  node_course_definition["Course spec<br/>yml entrypoint"]
  node_stage_descriptions["Stage docs"]
  node_repo_docs["Repo docs<br/>documentation<br/>[README.md]"]
end

subgraph group_templates["Starter pipeline"]
  node_starter_templates["Starter templates<br/>template source"]
  node_language_builds["Build files<br/>ecosystem build"]
  node_runner_scripts["Runner scripts<br/>portability shim"]
  node_template_entrypoints["Entrypoints<br/>starter main"]
end

subgraph group_artifacts["Generated artifacts"]
  node_compiled_starters["Compiled starters<br/>generated starters"]
  node_compiled_wrappers["Packaged scripts<br/>generated runtime"]
  node_compiled_entrypoints["Packed code<br/>starter code"]
  node_solutions["Solutions<br/>solution snapshots"]
  node_solution_revisions["Revisions<br/>versioned solves"]
  node_solution_code["Solution code<br/>completed app"]
  node_solution_diffs["Diffs<br/>change set"]
  node_solution_config["Config<br/>solution metadata"]
end

subgraph group_infra["Validation infra"]
  node_dockerfiles["Docker matrix<br/>toolchain images"]
  node_ci_workflow["CI check<br/>github workflow<br/>[test.yml]"]
end

node_course_definition -->|"orders"| node_stage_descriptions
node_course_definition -->|"drives"| node_starter_templates
node_stage_descriptions -.->|"defines tasks"| node_starter_templates
node_starter_templates -->|"contains"| node_language_builds
node_starter_templates -->|"contains"| node_runner_scripts
node_starter_templates -->|"contains"| node_template_entrypoints
node_runner_scripts -.->|"executes in"| node_dockerfiles
node_dockerfiles -.->|"produces"| node_compiled_starters
node_starter_templates -->|"generates"| node_compiled_starters
node_compiled_starters -->|"contains"| node_compiled_wrappers
node_compiled_starters -->|"contains"| node_compiled_entrypoints
node_starter_templates -.->|"mirrors"| node_solutions
node_solutions -->|"organizes"| node_solution_revisions
node_solution_revisions -->|"contains"| node_solution_code
node_solution_revisions -->|"tracks"| node_solution_diffs
node_solution_revisions -.->|"annotates"| node_solution_config
node_ci_workflow -->|"validates"| node_course_definition
node_ci_workflow -->|"validates"| node_starter_templates
node_ci_workflow -->|"validates"| node_compiled_starters
node_ci_workflow -.->|"validates"| node_solutions
node_repo_docs -.->|"describes"| node_course_definition

click node_course_definition "https://github.com/codecrafters-io/build-your-own-redis/blob/main/course-definition.yml"
click node_stage_descriptions "https://github.com/codecrafters-io/build-your-own-redis/tree/main/stage_descriptions"
click node_starter_templates "https://github.com/codecrafters-io/build-your-own-redis/tree/main/starter_templates"
click node_compiled_starters "https://github.com/codecrafters-io/build-your-own-redis/tree/main/compiled_starters"
click node_solutions "https://github.com/codecrafters-io/build-your-own-redis/tree/main/solutions"
click node_dockerfiles "https://github.com/codecrafters-io/build-your-own-redis/tree/main/dockerfiles"
click node_ci_workflow "https://github.com/codecrafters-io/build-your-own-redis/blob/main/.github/workflows/test.yml"
click node_repo_docs "https://github.com/codecrafters-io/build-your-own-redis/blob/main/README.md"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_course_definition,node_stage_descriptions,node_repo_docs toneBlue
class node_starter_templates,node_language_builds,node_runner_scripts,node_template_entrypoints toneAmber
class node_compiled_starters,node_compiled_wrappers,node_compiled_entrypoints,node_solutions,node_solution_revisions,node_solution_code,node_solution_diffs,node_solution_config toneMint
class node_dockerfiles,node_ci_workflow toneRose
```

## Components

### Authoring

Course content and narrative sources.

- [Course spec](https://github.com/codecrafters-io/build-your-own-redis/blob/main/course-definition.yml): yml entrypoint · Main course definition for the Redis challenge. · `course-definition.yml`
- [Stage docs](https://github.com/codecrafters-io/build-your-own-redis/tree/main/stage_descriptions): stage docs · Human-readable stage narratives for Redis feature progression. · `stage_descriptions`
- [Repo docs](https://github.com/codecrafters-io/build-your-own-redis/blob/main/README.md): documentation · Top-level README and license scaffolding. · `README.md`

### Starter pipeline

Language scaffolds and their packaging flow.

- [Starter templates](https://github.com/codecrafters-io/build-your-own-redis/tree/main/starter_templates): template source · Canonical per-language learner project skeletons. · `starter_templates`
- **Build files**: ecosystem build · Language-native manifests and build metadata inside starters.
- **Runner scripts**: portability shim · Standard compile/run wrappers that normalize execution across languages.
- **Entrypoints**: starter main · Minimal language-specific program entry files in the starter set.

### Generated artifacts

Compiled starters and solution snapshots.

- [Compiled starters](https://github.com/codecrafters-io/build-your-own-redis/tree/main/compiled_starters): generated starters · Packaged, ready-to-run outputs of the starter template pipeline. · `compiled_starters`
- **Packaged scripts**: generated runtime · The codecrafters wrapper layer embedded in compiled starters.
- **Packed code**: starter code · Language entry files in the compiled starter output.
- [Solutions](https://github.com/codecrafters-io/build-your-own-redis/tree/main/solutions): solution snapshots · Completed implementations across languages and revisions. · `solutions`
- **Revisions**: versioned solves · Named solution states such as 01-jm1, 02-rg2, and 03-wy1.
- **Solution code**: completed app · Per-revision code snapshots aligned with the starter structure.
- **Diffs**: change set · Patch folders showing how each solution evolved.
- **Config**: solution metadata · Optional per-revision metadata files.

### Validation infra

Container matrix and CI checks.

- [Docker matrix](https://github.com/codecrafters-io/build-your-own-redis/tree/main/dockerfiles): toolchain images · Versioned containers for the supported language/runtime matrix. · `dockerfiles`
- [CI check](https://github.com/codecrafters-io/build-your-own-redis/blob/main/.github/workflows/test.yml): github workflow · Repository validation workflow for templates and generated assets. · `.github/workflows/test.yml`

## Connections

- Course spec → Stage docs: orders · The course definition is elaborated by stage-by-stage teaching content.
- Course spec → Starter templates: drives · The course spec points learners into language-specific starter projects.
- Stage docs → Starter templates: defines tasks · Stage narratives define what the starters must support.
- Starter templates → Build files: contains · Each starter includes ecosystem-specific build metadata.
- Starter templates → Runner scripts: contains · Each starter includes standardized compile/run wrappers.
- Starter templates → Entrypoints: contains · Each starter includes a minimal entry file.
- Runner scripts → Docker matrix: executes in · Wrapper scripts run inside versioned language containers.
- Docker matrix → Compiled starters: produces · Containerized toolchains produce ready-to-run starter artifacts.
- Starter templates → Compiled starters: generates · Compiled starters are the packaged output of the template pipeline.
- Compiled starters → Packaged scripts: contains · Packaged starters retain the normalized runtime wrapper layer.
- Compiled starters → Packed code: contains · Packaged starters include the starter application entrypoints.
- Starter templates → Solutions: mirrors · Solutions follow the same structural shape as the starter templates.
- Solutions → Revisions: organizes · Solutions are grouped into named revisions per language.
- Revisions → Solution code: contains · Each revision contains the implemented code snapshot.
- Revisions → Diffs: tracks · Each revision includes a diff from the previous state.
- Revisions → Config: annotates · Some revisions include per-state metadata.
- CI check → Course spec: validates · CI checks course-level consistency.
- CI check → Starter templates: validates · CI checks starter integrity across supported languages.
- CI check → Compiled starters: validates · CI checks generated starter artifacts.
- CI check → Solutions: validates · CI can also verify solution snapshots and derived assets.
- Repo docs → Course spec: describes · Repository docs explain the course and its scaffolding.