# How ROADMAP.md Tracks Lesson Completion Status in AI Engineering from Scratch

> Learn how ROADMAP.md tracks AI Engineering lesson completion using Unicode glyphs. Discover how status indicators power the curriculum website and llms.txt.

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

---

**[`ROADMAP.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/ROADMAP.md) tracks lesson completion status through three Unicode glyphs—✅, 🚧, and ⬚—which are parsed by [`site/build.js`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/site/build.js) into plain-text status strings that power the curriculum website and [`llms.txt`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/llms.txt).**

The `rohitg00/ai-engineering-from-scratch` repository uses a single markdown file to coordinate progress across its entire curriculum. According to the project source code, [`ROADMAP.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/ROADMAP.md) serves as the human-editable source of truth for lesson completion status, encoding state information with plain Unicode characters that automated build scripts consume during site generation. This lightweight architecture keeps the curriculum state in sync without requiring contributors to edit JSON or configuration files directly.

## Status Glyphs in ROADMAP.md

[`ROADMAP.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/ROADMAP.md) encodes progress with three distinct Unicode symbols that are easy to scan and simple to update:

- **✅ Complete** – the lesson has been implemented and passes its tests.
- **🚧 In Progress** – work is underway but not yet finished.
- **⬚ Planned** – the lesson is defined but not started.

## Phase-Level and Lesson-Level Status Tracking

These glyphs appear in two specific locations inside the roadmap file.

1. **Phase headers** – for example, `## Phase 0: Setup & Tooling — ✅` indicates the overall status of the entire phase.

2. **Lesson rows** – each lesson is listed in a Markdown table row such as `| 01 | Dev Environment | ✅ | ~75 min |`. The third column holds the lesson’s status glyph.

## Parsing ROADMAP.md in site/build.js

During site generation, the Node script [`site/build.js`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/site/build.js) reads [`ROADMAP.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/ROADMAP.md) and converts glyphs into structured status data. The `parseRoadmap()` function iterates over every line, applying regular expressions to capture both phase headers and lesson rows.

```js
// site/build.js – extract status from ROADMAP.md
function parseRoadmap(content) {
  const statuses = {};                     // → { "Phase 0": { phaseStatus, lessons: { … } } }
  let currentPhase = null;
  let currentPhaseStatus = null;

  for (const line of content.split(/\r?\n/)) {
    // Phase header, e.g. "## Phase 0 … — ✅"

    const phaseMatch = line.match(/^##\s+Phase\s+(\d+).*?—\s*(✅|🚧|⬚)/);
    if (phaseMatch) {
      const phaseId = parseInt(phaseMatch[1]);
      const statusEmoji = phaseMatch[2];
      currentPhaseStatus = statusEmoji === '✅' ? 'complete'
                         : statusEmoji === '🚧' ? 'in-progress'
                         : 'planned';
      currentPhase = `Phase ${phaseId}`;
      statuses[currentPhase] = { phaseStatus: currentPhaseStatus, lessons: {} };
      continue;
    }

    // Lesson row, e.g. "| 01 | Dev Environment | ✅ |"
    if (currentPhase) {
      const lessonMatch = line.match(/^\|\s*\d+\s*\|\s*(.+?)\s*\|\s*(✅|🚧|⬚)\s*\|/);
      if (lessonMatch) {
        const lessonName = lessonMatch[1].trim();
        const statusEmoji = lessonMatch[2];
        const status = statusEmoji === '✅' ? 'complete'
                     : statusEmoji === '🚧' ? 'in-progress'
                     : 'planned';
        statuses[currentPhase].lessons[lessonName] = status;
      }
    }
  }
  return statuses;
}

```

The resulting `statuses` object is merged with lesson links extracted from [`README.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/README.md) so that the generated [`site/data.js`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/site/data.js) contains both a destination URL and a real-time `status` field for every lesson.

## Downstream Consumption and Site Generation

The structured data produced by `parseRoadmap()` drives multiple outputs across the curriculum site. It populates the visual roadmap page ([`prereqs.html`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/prereqs.html)), powers badge counts for total and completed lessons, and feeds the [`llms.txt`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/llms.txt) file used by AI agents to discover the curriculum. Because the site generator combines [`ROADMAP.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/ROADMAP.md) statuses with [`README.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/README.md) links, the entire curriculum state is kept in a single, human-readable file.

Page components can consume the generated status field to render colour-coded badges:

```js
// Example: rendering a lesson list with colour‑coded badges
function renderLesson(lesson) {
  const colour = { complete: 'green', 'in-progress': 'orange', planned: 'gray' }[lesson.status];
  return `<li style="color:${colour}">${lesson.name}</li>`;
}

```

## Manually Updating Lesson Completion Status

Because the glyphs are plain Unicode characters, contributors can edit [`ROADMAP.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/ROADMAP.md) directly without touching JSON or configuration files. For example, changing a table cell from `⬚` to `✅` marks the lesson as finished:

```markdown
| 03 | Matrix Transformations & Eigenvalues | ✅ | ~75 min |

```

After the commit merges, the CI pipeline reruns [`site/build.js`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/site/build.js), which rebuilds [`site/data.js`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/site/data.js) and updates all derived artefacts automatically.

You can verify the parser locally by reading the markdown file and asserting the expected phase and lesson statuses:

```js
const roadmap = fs.readFileSync('ROADMAP.md', 'utf8');
const statuses = parseRoadmap(roadmap);
console.assert(statuses['Phase 0'].phaseStatus === 'complete');
console.assert(statuses['Phase 0'].lessons['Dev Environment'] === 'complete');

```

## Summary

- [`ROADMAP.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/ROADMAP.md) uses three Unicode glyphs—**✅**, **🚧**, and **⬚**—to encode lesson completion status at both phase and lesson levels.
- The `parseRoadmap()` function in [`site/build.js`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/site/build.js) scans the markdown with regexes and converts glyphs into the strings `complete`, `in-progress`, and `planned`.
- Parsed status data is merged with [`README.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/README.md) lesson links to produce [`site/data.js`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/site/data.js), which drives [`prereqs.html`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/prereqs.html), badge counts, and [`llms.txt`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/llms.txt).
- Manual updates to [`ROADMAP.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/ROADMAP.md) propagate automatically through the CI pipeline, keeping the curriculum state in sync without extra tooling.

## Frequently Asked Questions

### What do the status emojis in ROADMAP.md represent?

The three glyphs serve as a lightweight visual tracker: **✅** means the lesson is complete and passes tests, **🚧** means work is actively in progress, and **⬚** means the lesson is planned but not yet started. These symbols appear in both phase headers and individual lesson table rows, making the curriculum state readable at a glance.

### How does site/build.js parse the roadmap statuses?

The `parseRoadmap()` function in [`site/build.js`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/site/build.js) scans every line of [`ROADMAP.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/ROADMAP.md) using regular expressions that match phase headers (`/^##\s+Phase\s+(\d+).*?—\s*(✅|🚧|⬚)/`) and lesson rows (`/^\|\s*\d+\s*\|\s*(.+?)\s*\|\s*(✅|🚧|⬚)\s*\|/`). It maps each matched glyph to the string `complete`, `in-progress`, or `planned`, then returns a nested `statuses` object organized by phase and lesson name.

### Can I manually update a lesson's completion status?

Yes. Because the glyphs are plain Unicode characters, you can edit [`ROADMAP.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/ROADMAP.md) directly and commit the change. The CI pipeline then reruns [`site/build.js`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/site/build.js), which propagates the updated status into [`site/data.js`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/site/data.js), the visual roadmap page, and the [`llms.txt`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/llms.txt) file automatically.

### What downstream assets depend on ROADMAP.md?

The parsed status object is merged with [`README.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/README.md) links to produce [`site/data.js`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/site/data.js), which fuels the [`prereqs.html`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/prereqs.html) roadmap page and badge counters across the site. The same data set also populates [`llms.txt`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/llms.txt), allowing AI agents to discover the current curriculum state as implemented in `rohitg00/ai-engineering-from-scratch`.