# ROADMAP.md Status Tracking System for Lesson Completion in AI Engineering From Scratch

> Discover the ROADMAP.md status tracking system for AI Engineering From Scratch. Learn how emojis and a Node.js parser create structured JSON for lesson completion.

- Repository: [Rohit Ghumare/ai-engineering-from-scratch](https://github.com/rohitg00/ai-engineering-from-scratch)
- Tags: getting-started
- Published: 2026-06-22

---

**The ROADMAP.md status tracking system uses a machine-readable, emoji-based markup scheme where contributors update markdown tables with completion glyphs (✅, 🚧, ⬚) that a Node.js parser converts into structured JSON to power the project's website.**

The AI Engineering From Scratch curriculum maintains lesson progress through an elegant single-file tracking approach. Instead of relying on external project management tools, the repository uses a standardized markdown table format in [`ROADMAP.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/ROADMAP.md) that serves as the **single source of truth** for curriculum completion. This approach allows both humans and automation to read progress status directly from version-controlled markdown.

## How the ROADMAP.md Table Structure Works

Each phase of the curriculum is represented by a markdown table containing lesson metadata and a dedicated **Status** column. The table follows a strict schema with five columns: lesson number, title (with link), status glyph, and time estimate.

In [`ROADMAP.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/ROADMAP.md), a typical entry looks like this:

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

|---|--------|------------|------|
| 01 | Dev Environment | ✅ | ~75 min |
| 02 | Git & Collaboration | ✅ | ~45 min |
| 13 | [Attention Mechanism — The Breakthrough](phases/05-nlp-foundations-to-advanced/10-attention-mechanism) | ⬚ | ~45 min |

```

The **status column** is the only field that changes during development. When work begins on a lesson, the author updates the glyph from `⬚` to `🚧`, and upon completion, replaces it with `✅`.

## Status Glyph Legend

The top of [`ROADMAP.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/ROADMAP.md) defines a three-state emoji legend that standardizes progress communication across the curriculum:

- **`✅`** — *Complete*: The lesson content is finalized and published
- **`🚧`** — *In Progress*: Active development is underway
- **`⬚`** — *Planned*: Scheduled for future development but not yet started

This glyph system creates a **human-readable and machine-parsable** interface. Contributors can scan the markdown visually to understand progress, while automated tooling extracts these Unicode characters to generate statistics and UI components.

To mark a lesson as complete, you simply edit the table cell:

```markdown
| 13 | [Attention Mechanism — The Breakthrough](phases/05-nlp-foundations-to-advanced/10-attention-mechanism) | ✅ | ~45 min |

```

## Build Pipeline Automation

The repository automates website updates by parsing [`ROADMAP.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/ROADMAP.md) on every commit. The build pipeline consists of three interconnected components that keep documentation synchronized without manual intervention.

### 1. Parsing with site/build.js

The Node.js script [`site/build.js`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/site/build.js) contains the `parseRoadmap` function (lines 31-37) that scans the markdown file, detects phase headers, and extracts table rows into structured objects:

```javascript
function parseRoadmap(content) {
  const lines = content.split('\n');
  const roadmap = {};
  // ...detect phase headers, then table rows
  // each row yields: { phase, lessonNumber, title, statusGlyph, est }
  return roadmap;
}

```

This function treats the emoji glyphs as discrete state tokens, converting the visual markdown representation into programmatic data.

### 2. Data Generation for the Website

The parsed output is written to **[`site/data.js`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/site/data.js)**, which powers the lesson catalog and progress widgets. The conversion produces JSON objects like:

```json
{
  "phase": "Phase 5: NLP",
  "lesson": "10",
  "title": "Attention Mechanism — The Breakthrough",
  "status": "✅",
  "estimate": "~45 min"
}

```

### 3. CI/CD Integration

The [`curriculum.yml`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/curriculum.yml) CI job runs [`site/build.js`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/site/build.js) on every push to the repository. This automation updates the README lesson counts and regenerates site assets immediately after [`ROADMAP.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/ROADMAP.md) changes, ensuring the live website reflects the current curriculum state without requiring additional build steps from contributors.

## Summary

- **[`ROADMAP.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/ROADMAP.md)** acts as the central progress tracker using markdown tables with emoji status glyphs
- **Three-state system**: ✅ (Complete), 🚧 (In Progress), ⬚ (Planned) provides unambiguous lesson states
- **[`site/build.js`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/site/build.js)** parses the roadmap and converts markdown tables into JSON data structures
- **Continuous integration** automatically synchronizes the website whenever status changes are pushed

## Frequently Asked Questions

### What do the emoji symbols in ROADMAP.md mean?

The emoji symbols represent discrete lesson states: ✅ indicates a complete lesson, 🚧 marks lessons currently in development, and ⬚ designates planned content that has not yet started. These glyphs appear in the **Status** column of the markdown tables and are defined in the legend at the top of [`ROADMAP.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/ROADMAP.md).

### How does the website stay synchronized with ROADMAP.md changes?

The synchronization happens automatically through the [`curriculum.yml`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/curriculum.yml) CI pipeline. When you push changes to [`ROADMAP.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/ROADMAP.md), the CI job executes [`site/build.js`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/site/build.js), which parses the updated tables and writes fresh data to [`site/data.js`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/site/data.js). This triggers a site rebuild that displays the current lesson completion status without requiring manual website updates.

### Can I manually edit lesson status without running the build script locally?

Yes. Since [`ROADMAP.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/ROADMAP.md) is plain markdown, you can edit the status glyphs directly in any text editor or through GitHub's web interface. The CI pipeline handles the build process automatically after you commit changes, so local builds are only necessary for development or testing the parser logic.

### What happens if I use an incorrect status emoji in the table?

The `parseRoadmap` function in [`site/build.js`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/site/build.js) extracts whatever glyph appears in the status column, so using an undefined emoji will not break the build but may cause the website to display incorrect status indicators. Stick to the three defined glyphs (✅, 🚧, ⬚) to ensure consistent rendering in the lesson catalog and progress widgets.