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

> Discover the status tracking system in the ai-engineering-from-scratch ROADMAP.md file. Learn how Unicode glyphs manage curriculum progress for dynamic website updates.

- Repository: [Rohit Ghumare/ai-engineering-from-scratch](https://github.com/rohitg00/ai-engineering-from-scratch)
- Tags: architecture
- Published: 2026-07-30

---

**The [`ROADMAP.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/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:

```markdown
| # | 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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/site/build.js) scans every table in [`ROADMAP.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/ROADMAP.md), extracts the Unicode status glyphs, and transforms them into structured data. This process writes to [`site/data.js`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/scripts/audit_lessons.py) in the CI pipeline. This script cross-references the Unicode status glyphs written in [`ROADMAP.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/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:

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

```

Once development begins, update the glyph:

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

```

Upon completion and validation, set to complete:

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

```

### Reading Statuses Programmatically

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

```javascript
// 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)](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)](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:

```jsx
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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/ROADMAP.md) uses a four-column Markdown table where the **Status** column contains only ✅, 🚧, or ⬚ glyphs to indicate lesson lifecycle states
- [`site/build.js`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/site/build.js) parses these Unicode symbols from [`ROADMAP.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/ROADMAP.md) to generate [`site/data.js`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/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`](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), extracts the status glyphs from the Markdown tables using pattern matching, and outputs structured JSON-like data to [`site/data.js`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/scripts/audit_lessons.py), which cross-references the Unicode status glyphs recorded in [`ROADMAP.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/ROADMAP.md) explicitly warn contributors not to alter the glyphs on line 9. The parser in [`site/build.js`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/site/build.js) relies on exact Unicode matches for ✅, 🚧, and ⬚ to correctly generate [`site/data.js`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/site/data.js). Changing these symbols would break the website's ability to track and display curriculum progress.