# How ROADMAP.md Tracks the Completion Status of Lessons in ai-engineering-from-scratch

> Discover how ROADMAP.md in ai-engineering-from-scratch uses emojis to track lesson completion status. Learn how site build scripts process these statuses for the project website.

- Repository: [Rohit Ghumare/ai-engineering-from-scratch](https://github.com/rohitg00/ai-engineering-from-scratch)
- Tags: how-to-guide
- Published: 2026-06-05

---

**ROADMAP.md tracks lesson completion status by embedding ✅, 🚧, and ⬚ emojis directly into markdown phase headers and lesson tables, which [`site/build.js`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/site/build.js) parses into canonical `complete`, `in-progress`, and `planned` strings to power the project website and [`site/data.js`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/site/data.js).**

The `rohitg00/ai-engineering-from-scratch` repository treats **[`ROADMAP.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/ROADMAP.md)** as the single source of truth for curriculum progress. This file blends human-readable visual markers with a deterministic parsing pipeline, ensuring instructors and automated tooling agree on exactly which lessons are finished, active, or pending.

## The Three-Glyph Status Legend

[`ROADMAP.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/ROADMAP.md) encodes every lesson state with one of three Unicode glyphs. These symbols provide an at-a-glance view of the entire curriculum without requiring readers to interpret metadata files or JSON schemas.

- **✅ Complete** – the lesson has been delivered and its code or tests pass.
- **🚧 In Progress** – active development is underway but the lesson is not yet finished.
- **⬚ Planned** – the lesson is scheduled for future work and has not been started.

## Where Status Appears in ROADMAP.md

The emojis appear in two specific locations inside the markdown file. Phase headers show aggregate progress, while individual lesson rows provide granular, at-a-glance detail for every curriculum item.

### Phase Headers

Each phase declares its overall health in the section title itself. The emoji appears after an em-dash, making the aggregate state visible before readers scroll to individual lessons.

```markdown

## Phase 0: Setup & Tooling — ✅

```

### Lesson Table Rows

Within each phase, lessons live in markdown tables with a dedicated **Status** column. Every row binds a lesson name to its current glyph so readers can scan progress instantly, as implemented in `rohitg00/ai-engineering-from-scratch`.

```markdown
| # | Lesson | Status | Est. |

|---|--------|--------|------|
| 01 | Dev Environment | ✅ | ~75 min |

```

## How site/build.js Parses ROADMAP.md into Structured Data

The build script located at **[`site/build.js`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/site/build.js)** scans [`ROADMAP.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/ROADMAP.md) line-by-line to extract the visual state and convert it into machine-readable strings. This normalization occurs around lines 30–48 of the script and removes all emoji-handling complexity from downstream consumers.

### Phase-Level Extraction

A regular expression targets phase headers to capture the trailing emoji. It then maps that symbol to a canonical string representing the overall phase health.

```javascript
// Phase header → overall phase status
const phaseMatch = line.match(/^##\s+Phase\s+(\d+).*?—\s*(✅|🚧|⬚)/);
if (phaseMatch) {
  const statusEmoji = phaseMatch[2];
  currentPhaseStatus = statusEmoji === '✅' ? 'complete'
                    : statusEmoji === '🚧' ? 'in-progress' : 'planned';
  // store under statuses[currentPhase]...
}

```

### Lesson-Level Extraction

After identifying a phase, a second regex matches table rows containing lesson data. It extracts the lesson name and status emoji, then stores the mapped value in the `statuses` object for later consumption.

```javascript
// Lesson row → per-lesson status
const lessonMatch = line.match(/^\|\s*\d+\s*\|\s*(.+?)\s*\|\s*(✅|🚧|⬚)\s*\|/);
if (lessonMatch) {
  const statusEmoji = lessonMatch[2];
  const status = statusEmoji === '✅' ? 'complete'
               : statusEmoji === '🚧' ? 'in-progress' : 'planned';
  statuses[currentPhase].lessons[lessonName] = status;
}

```

## Feeding the Website Pipeline

Once parsed, the `statuses` object is merged with lesson content extracted from [`README.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/README.md). During this alignment step inside the build pipeline, the script performs a fuzzy match between lesson names documented in the roadmap and those described in the readme.

```javascript
let status = 'planned';
if (roadmapPhase) {
  // fuzzy match lesson name → status from ROADMAP
  for (const [rName, rStatus] of Object.entries(roadmapPhase.lessons)) {
    if (matchesLessonName(rName, lessonName)) {
      status = rStatus;
      break;
    }
  }
}

```

The final aggregated data is written to **[`site/data.js`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/site/data.js)**, where the status strings drive visual icons, progress indicators, and curriculum queries on the project website.

## Summary

- **ROADMAP.md** embeds ✅, 🚧, and ⬚ emojis in phase headers and lesson tables to indicate completion, in-progress, and planned states.
- **[`site/build.js`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/site/build.js)** uses two targeted regular expressions to extract and normalize these emojis into machine-readable strings around lines 30–48.
- The resulting `statuses` object is merged with [`README.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/README.md) content and serialized to [`site/data.js`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/site/data.js) for the website frontend.

## Frequently Asked Questions

### What do the ✅, 🚧, and ⬚ emojis mean in ROADMAP.md?

The ✅ emoji marks a lesson or phase as **Complete**, meaning it has been delivered and its associated code or tests pass. The 🚧 emoji indicates the item is **In Progress**, while the ⬚ emoji means it is **Planned** but not yet started.

### How does [`site/build.js`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/site/build.js) know which status emoji belongs to which lesson?

The script runs two regex passes over [`ROADMAP.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/ROADMAP.md). The first matches `## Phase … — [emoji]` to set the current phase context, and the second matches `| ## | Lesson Name | [emoji] |` to bind each row's emoji to that phase's `statuses` object under the lesson name key.

### Can I update a lesson's completion status by editing ROADMAP.md manually?

Yes. Because [`ROADMAP.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/ROADMAP.md) is the single source of truth, changing an emoji in the markdown table and re-running the build script will update the canonical status in [`site/data.js`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/site/data.js). No separate database or configuration file needs to be modified.

### Where does the parsed status data end up after the build script runs?

The normalized status values are stored in a JavaScript object that is merged with [`README.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/README.md) lesson metadata and emitted to [`site/data.js`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/site/data.js). This file powers the visual icons and progress indicators rendered on the project website.