Status Tracking System in ROADMAP.md: How AI Engineering From Scratch Manages Curriculum Progress

The ROADMAP.md file in rohitg00/ai-engineering-from-scratch uses three specific Unicode glyphs (✅, 🚧, ⬚) within Markdown tables to track lesson completion states, with the static site generator parsing these symbols to produce dynamic progress bars and completion statistics on the project website.

The ai-engineering-from-scratch repository maintains a comprehensive open-source curriculum for learning AI engineering. The status tracking system outlined in ROADMAP.md serves as the single source of truth for curriculum development, utilizing a machine-readable table format that feeds directly into the build pipeline, CI validation, and frontend rendering systems.

Anatomy of the ROADMAP.md Status Table

The Three-State Glyph Legend

The Status column in ROADMAP.md relies on a strict set of three Unicode symbols defined on line 9. The file header explicitly warns on lines 3-5 that these glyphs must remain unchanged because the parser in site/build.js matches them deterministically:

Glyph	State	Description
✅	Complete	The lesson has been fully authored, its code runs successfully, and all tests pass.
🚧	In Progress	Development work is currently underway but not yet finished.
⬚	Planned	The lesson is scheduled for development but has not started.

Four-Column Table Structure

Each phase and lesson is listed in a Markdown table containing exactly four columns:

| # | Lesson | Status | Est. |

|---|--------|--------|------|

The Est. column records the estimated time for each lesson (e.g., "~75 min"). These values are summed per phase and displayed in the phase heading, such as "Phase 0: Setup & Tooling — ✅ (~14 hours)", giving learners an immediate sense of total time investment required.

Build Pipeline Integration

Parsing ROADMAP.md in site/build.js

The static site generator located at site/build.js scans every table in ROADMAP.md, extracts the Unicode status glyphs, and transforms them into structured data. This process writes to site/data.js, which contains the lesson metadata required to render the curriculum overview.

Because the glyphs are the only machine-readable indicators of lesson state, the parser expects exactly these three characters (\u2705, \u1F6A7, \u23DA). Any deviation would break the build process that generates the website's data layer.

Frontend Consumption of site/data.js

The generated site/data.js file is imported by the React frontend to create interactive features. The website uses this data to:

• Render phase-level progress bars showing completion percentages
• Filter lesson lists by status (e.g., "Show only completed lessons")
• Compute overall curriculum completion statistics

CI Validation and Data Integrity

To prevent documentation drift, the repository includes scripts/audit_lessons.py in the CI pipeline. This script cross-references the Unicode status glyphs written in ROADMAP.md against the actual state of each lesson's code directory and test files. If a lesson is marked ✅ but fails tests or is missing implementation files, the CI build fails, enforcing consistency between the roadmap and the repository's actual contents.

Practical Usage Examples

Updating Lesson Status During Development

When adding a new lesson to the curriculum, contributors initialize the row with the planned state:

| 12 | Attention Mechanisms | ⬚ | ~90 min |

Once development begins, update the glyph:

| 12 | Attention Mechanisms | 🚧 | ~90 min |

Upon completion and validation, set to complete:

| 12 | Attention Mechanisms | ✅ | ~90 min |

Reading Statuses Programmatically

The following Node.js snippet illustrates how the build system consumes the glyph data:

// parseRoadmap.js - Simplified extraction logic
import fs from 'fs';

const text = fs.readFileSync('ROADMAP.md', 'utf8');
const lines = text.split('\n');
const statusPattern = /\|\s*\d+\s*\|\s*.+?\|\s*(✅|🚧|⬚)\s*\|/;
const statuses = [];

for (const line of lines) {
  const match = line.match(statusPattern);
  if (match) statuses.push(match[1]);
}

console.log('Extracted lesson statuses:', statuses);

The production parser in [site/build.js](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/site/build.js) writes its output to [site/data.js](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/site/data.js) for frontend consumption.

Filtering by Status in React

To display only completed lessons in a component:

import data from '../site/data.js';

const completedLessons = data.lessons.filter(l => l.status === '✅');

export default function Curriculum() {
  return (
    <LessonList lessons={completedLessons} />
  );
}

Summary

• ROADMAP.md uses a four-column Markdown table where the Status column contains only ✅, 🚧, or ⬚ glyphs to indicate lesson lifecycle states
• site/build.js parses these Unicode symbols from ROADMAP.md to generate site/data.js, which drives the website's progress bars and filtering capabilities
• Phase headings aggregate the Est. column values to display total required hours (e.g., "~14 hours")
• scripts/audit_lessons.py enforces data integrity by validating that roadmap statuses match actual code implementation during CI runs

Frequently Asked Questions

What do the three symbols in ROADMAP.md mean?

The status tracking system uses ✅ to indicate a completed lesson where all code runs and tests pass, 🚧 to mark lessons currently under active development, and ⬚ for planned lessons that have not yet begun. These specific Unicode glyphs are required because the static site generator parses them to create the dynamic progress indicators on the website.

How does the website generate progress bars from the roadmap?

The Node.js build script site/build.js reads ROADMAP.md, extracts the status glyphs from the Markdown tables using pattern matching, and outputs structured JSON-like data to site/data.js. The React frontend imports this generated file to render progress bars, calculate phase completion percentages, and provide status-based filtering options.

What prevents the roadmap status from becoming outdated?

The CI pipeline automatically executes scripts/audit_lessons.py, which cross-references the Unicode status glyphs recorded in ROADMAP.md against the actual presence of lesson code and test results. This prevents scenarios where a lesson is marked complete in the documentation but fails validation or is missing implementation in the repository.

Can I change the status symbols to different characters?

No. Lines 3-5 of ROADMAP.md explicitly warn contributors not to alter the glyphs on line 9. The parser in site/build.js relies on exact Unicode matches for ✅, 🚧, and ⬚ to correctly generate site/data.js. Changing these symbols would break the website's ability to track and display curriculum progress.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}