# madhank93/build-your-own-x architecture

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

- Interactive diagram: https://gitdiagram.com/madhank93/build-your-own-x
- Repository: https://github.com/madhank93/build-your-own-x

## Overview

byox is a local CodeCrafters course runner: a learner selects a course and stage in the TUI, runs the official tester against their solution, and records passing progress so later stages unlock. The repository also includes course registration and validation, learning notes, reference solutions, and a generated web catalog. The README documents the main workflow; sampled source confirms the catalog generator’s inputs. Several engine and course subsystems are represented from the tree and README rather than inspected source, so their internal links are omitted where evidence is unavailable.

Main entry points: [`engine/internal/tui/tui.go`](https://github.com/madhank93/build-your-own-x/blob/main/engine/internal/tui/tui.go) (Interactive TUI), [`engine/internal/runner/run.go`](https://github.com/madhank93/build-your-own-x/blob/main/engine/internal/runner/run.go) (Test runner), [`web/gen/main.go`](https://github.com/madhank93/build-your-own-x/blob/main/web/gen/main.go) (Catalog generator), [`engine/internal/progress/progress.go`](https://github.com/madhank93/build-your-own-x/blob/main/engine/internal/progress/progress.go) (Stage progress)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runner["Local runner"]
  node_cli["byox CLI<br/>[main.go]"]
  node_tui["Interactive TUI<br/>[tui.go]"]
  node_tui_views["TUI views<br/>[overlay.go]"]
  node_log_buffer["Test log buffer<br/>[logbuf.go]"]
  node_watch["Watch mode<br/>[watch.go]"]
  node_help["TUI help<br/>[help.go]"]
  node_runner_exec["Test runner<br/>[run.go]"]
  node_setup["Course setup<br/>[setup.go]"]
  node_progress[("Stage progress<br/>[progress.go]")]
  node_diff["Stage diff<br/>[diff.go]"]
end

subgraph group_course["Course content"]
  node_registry["Course registry<br/>[registry.go]"]
  node_definition["Course definition<br/>[definition.go]"]
  node_validation["Course validation<br/>[validate.go]"]
  node_instructions["Stage instructions"]
  node_learning["Learning notes"]
end

subgraph group_solutions["Solutions"]
  node_user_solutions["Learner solutions"]
  node_reference_solutions["Reference solutions"]
end

subgraph group_web["Web catalog"]
  node_generator["Catalog generator<br/>[main.go]"]
  node_catalog["Web catalog<br/>[&#91;slug&#93;.json.ts]"]
end

node_learner(("Learner"))
node_tester["Official tester"]

node_learner -->|"selects stage"| node_tui
node_learner -->|"edits code"| node_user_solutions
node_tui -->|"runs tests"| node_runner_exec
node_watch -->|"reruns tests"| node_runner_exec
node_runner_exec -->|"tests code"| node_user_solutions
node_runner_exec -->|"invokes tester"| node_tester
node_runner_exec -->|"records passes"| node_progress
node_tui -->|"shows progress"| node_progress
node_tui -->|"renders instructions"| node_instructions
node_tui -->|"shows notes"| node_learning
node_tui -->|"shows solution"| node_reference_solutions
node_generator -->|"reads snapshots"| node_reference_solutions
node_generator -->|"reads notes"| node_learning
node_generator -->|"generates catalog data"| node_catalog
node_learner -->|"browses stages"| node_catalog

click node_cli "https://github.com/madhank93/build-your-own-x/blob/main/engine/cmd/byox/main.go"
click node_tui "https://github.com/madhank93/build-your-own-x/blob/main/engine/internal/tui/tui.go"
click node_tui_views "https://github.com/madhank93/build-your-own-x/blob/main/engine/internal/tui/overlay.go"
click node_log_buffer "https://github.com/madhank93/build-your-own-x/blob/main/engine/internal/tui/logbuf.go"
click node_watch "https://github.com/madhank93/build-your-own-x/blob/main/engine/internal/tui/watch.go"
click node_help "https://github.com/madhank93/build-your-own-x/blob/main/engine/internal/tui/help.go"
click node_runner_exec "https://github.com/madhank93/build-your-own-x/blob/main/engine/internal/runner/run.go"
click node_setup "https://github.com/madhank93/build-your-own-x/blob/main/engine/internal/runner/setup.go"
click node_progress "https://github.com/madhank93/build-your-own-x/blob/main/engine/internal/progress/progress.go"
click node_diff "https://github.com/madhank93/build-your-own-x/blob/main/engine/diff/diff.go"
click node_registry "https://github.com/madhank93/build-your-own-x/blob/main/engine/course/registry.go"
click node_definition "https://github.com/madhank93/build-your-own-x/blob/main/engine/course/definition.go"
click node_validation "https://github.com/madhank93/build-your-own-x/blob/main/engine/course/validate.go"
click node_learning "https://github.com/madhank93/build-your-own-x/tree/main/learn"
click node_user_solutions "https://github.com/madhank93/build-your-own-x/tree/main/solutions"
click node_reference_solutions "https://github.com/madhank93/build-your-own-x/tree/main/reference-solutions"
click node_generator "https://github.com/madhank93/build-your-own-x/blob/main/web/gen/main.go"
click node_catalog "https://github.com/madhank93/build-your-own-x/blob/main/web/src/pages/catalog-details/%5Bslug%5D.json.ts"

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_cli,node_tui,node_tui_views,node_log_buffer,node_watch,node_help,node_runner_exec,node_setup,node_progress,node_diff toneBlue
class node_registry,node_definition,node_validation,node_instructions,node_learning toneAmber
class node_user_solutions,node_reference_solutions toneMint
class node_generator,node_catalog toneRose
class node_learner,node_tester toneIndigo
```

## Components

### Local runner

- [byox CLI](https://github.com/madhank93/build-your-own-x/blob/main/engine/cmd/byox/main.go): `engine/cmd/byox/main.go`
- [Interactive TUI](https://github.com/madhank93/build-your-own-x/blob/main/engine/internal/tui/tui.go): `engine/internal/tui/tui.go`
- [TUI views](https://github.com/madhank93/build-your-own-x/blob/main/engine/internal/tui/overlay.go): `engine/internal/tui/overlay.go`
- [Test log buffer](https://github.com/madhank93/build-your-own-x/blob/main/engine/internal/tui/logbuf.go): `engine/internal/tui/logbuf.go`
- [Watch mode](https://github.com/madhank93/build-your-own-x/blob/main/engine/internal/tui/watch.go): `engine/internal/tui/watch.go`
- [TUI help](https://github.com/madhank93/build-your-own-x/blob/main/engine/internal/tui/help.go): `engine/internal/tui/help.go`
- [Test runner](https://github.com/madhank93/build-your-own-x/blob/main/engine/internal/runner/run.go): `engine/internal/runner/run.go`
- [Course setup](https://github.com/madhank93/build-your-own-x/blob/main/engine/internal/runner/setup.go): `engine/internal/runner/setup.go`
- [Stage progress](https://github.com/madhank93/build-your-own-x/blob/main/engine/internal/progress/progress.go): `engine/internal/progress/progress.go`
- [Stage diff](https://github.com/madhank93/build-your-own-x/blob/main/engine/diff/diff.go): `engine/diff/diff.go`

### Course content

- [Course registry](https://github.com/madhank93/build-your-own-x/blob/main/engine/course/registry.go): `engine/course/registry.go`
- [Course definition](https://github.com/madhank93/build-your-own-x/blob/main/engine/course/definition.go): `engine/course/definition.go`
- [Course validation](https://github.com/madhank93/build-your-own-x/blob/main/engine/course/validate.go): `engine/course/validate.go`
- **Stage instructions**
- [Learning notes](https://github.com/madhank93/build-your-own-x/tree/main/learn): `learn`

### Solutions

- [Learner solutions](https://github.com/madhank93/build-your-own-x/tree/main/solutions): `solutions`
- [Reference solutions](https://github.com/madhank93/build-your-own-x/tree/main/reference-solutions): `reference-solutions`

### Web catalog

- [Catalog generator](https://github.com/madhank93/build-your-own-x/blob/main/web/gen/main.go): `web/gen/main.go`
- [Web catalog](https://github.com/madhank93/build-your-own-x/blob/main/web/src/pages/catalog-details/%5Bslug%5D.json.ts): `web/src/pages/catalog-details/[slug].json.ts`

### Other components

- **Learner**
- **Official tester**

## Connections

- Learner → Interactive TUI: selects stage
- Learner → Learner solutions: edits code
- Interactive TUI → Test runner: runs tests
- Watch mode → Test runner: reruns tests
- Test runner → Learner solutions: tests code
- Test runner → Official tester: invokes tester
- Test runner → Stage progress: records passes
- Interactive TUI → Stage progress: shows progress
- Interactive TUI → Stage instructions: renders instructions
- Interactive TUI → Learning notes: shows notes
- Interactive TUI → Reference solutions: shows solution
- Catalog generator → Reference solutions: reads snapshots (evidence: `web/gen/main.go`)
- Catalog generator → Learning notes: reads notes (evidence: `web/gen/main.go`)
- Catalog generator → Web catalog: generates catalog data (evidence: `web/gen/main.go`)
- Learner → Web catalog: browses stages
