How codecrafters-io/build-your-own-redis works
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 Starter templates · compiled_starters Compiled starters · test.yml CI check · course-definition.yml Course spec
Components 17
Authoring
Course content and narrative sources.
- Course spec · Main course definition for the Redis challenge.
course-definition.yml - Stage docs · Human-readable stage narratives for Redis feature progression.
stage_descriptions - Repo docs · Top-level README and license scaffolding.
README.md
Starter pipeline
Language scaffolds and their packaging flow.
- Starter templates · Canonical per-language learner project skeletons.
starter_templates - Build files · Language-native manifests and build metadata inside starters.
- Runner scripts · Standard compile/run wrappers that normalize execution across languages.
- Entrypoints · Minimal language-specific program entry files in the starter set.
Generated artifacts
Compiled starters and solution snapshots.
- Compiled starters · Packaged, ready-to-run outputs of the starter template pipeline.
compiled_starters - Packaged scripts · The codecrafters wrapper layer embedded in compiled starters.
- Packed code · Language entry files in the compiled starter output.
- Solutions · Completed implementations across languages and revisions.
solutions - Revisions · Named solution states such as 01-jm1, 02-rg2, and 03-wy1.
- Solution code · Per-revision code snapshots aligned with the starter structure.
- Diffs · Patch folders showing how each solution evolved.
- Config · Optional per-revision metadata files.
Validation infra
Container matrix and CI checks.
- Docker matrix · Versioned containers for the supported language/runtime matrix.
dockerfiles - CI check · Repository validation workflow for templates and generated assets.
.github/workflows/test.yml
Connections 21
- 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.