Frontend Principal Journey

This repository is also a book. Build it with bash build.sh (or mdbook serve for live reload) and read it at http://localhost:3000. Start with the Introduction, the Phases & Modules index, and Toolchain Setup.

Modules fe-01 … fe-06 are built and measured: 22 experiments drive a real browser over CDP, and every table in the book is regenerated by npm run all inside that module's src/. See PHASES.md for status.

A structured learning repository for developing from frontend foundations through Principal/Distinguished-level frontend and web platform engineering.

Two tracks run in parallel, each driven by a specification file and organised as numbered module directories.

frontend-principal-journey/
├── frontend-principal-engineering.md    # spec: broad frontend track
├── browser-framework-internals.md       # spec: systems-construction track
│
├── fe-00-roadmap/ … fe-NN-…/            # FRONTEND track modules
├── fe-00-roadmap/docs/progress.md       #   ← its tracker
│
├── bi-00-roadmap/ … bi-16-capstone/     # BROWSER INTERNALS track modules
├── fw-01-… … fw-12-…/                   #   framework-internals strand
├── mini-browser/                        #   the spine, threaded through bi-03…bi-12
└── PROGRESS.md                          #   ← browser/framework tracker

Each module directory contains CONCEPTS.md (the explanation), docs/ (execution steps, observations, verification checkpoints), and src/ (runnable code).

A module is complete when its docs/verification.md checkpoints pass against measured or observed output, not when its prose has been read.

Track 1 — Frontend Principal Engineering

Spec: frontend-principal-engineering.md · Map: fe-00-roadmap/docs/curriculum-map.md · Tracker: fe-00-roadmap/docs/progress.md

Web foundations, JS/TS, HTML/CSS, React and framework architecture, state, APIs, networking, performance, accessibility, security, testing, design systems, platform engineering, build tooling, monorepos, microfrontends, rendering architectures, observability, reliability, CI/CD, i18n, mobile web, workers, WASM, migrations, ADRs, technical decision-making.

Track 2 — Browser & Framework Internals

Spec: browser-framework-internals.md · Map: bi-00-roadmap/CONCEPTS.md · Tracker: PROGRESS.md · Build guide: bi-00-roadmap/docs/chromium-build-debug-trace.md

Browser strand — navigating Chromium · architecture and process model · HTML parsing · DOM internals · bindings and V8 · Chromium C++ · CSS engine · layout · paint · compositor and GPU · scheduling · debugging and tracing · tests and WPT · contribution · vertical traces · capstone.

Framework strand — mini-redux · mini-react (core, then scheduling) · reactivity and signals · Vue-like renderer · compilers · bundler · router · query cache · virtualized list · production source apprenticeship · testing library and DevTools.

The two strands run in parallel and join at the vertical traces.

The learning loop

Use it -> predict (written, BEFORE observing) -> build a small version
-> intentionally break it -> debug it -> inspect production source
-> compare architectures -> explain why the complexity exists
-> modify production source where practical

Two rules make this work:

  • Predictions are written before observation. A clearly-stated wrong prediction is worth more than a vague right one.
  • Source paths are never handed to you. State a hypothesis, search, confirm or falsify, and record the query that worked. Queries transfer between subsystems; paths rot — see the verification log in PROGRESS.md §7 for dated evidence of exactly that.

How the tracks connect

Frontend Principal Engineering        Browser & Framework Internals
   architectural + org judgment          removes abstraction boundaries
              └──────────┬──────────────────────┘
                         ▼
                Principal Frontend SME

Cross-track sequencing is recorded in bi-00-roadmap/CONCEPTS.md §6 and fe-00-roadmap/docs/curriculum-map.md §2. It runs in both directions: the frontend track's execution-model module precedes Blink scheduling, while the internals track's mini-React precedes any reading about Fiber.

Shared across both tracks: learning-log.md (source readings, struggles, open questions) and decisions/ (ADRs).

Using this with coding agents

Browser/framework work: work from browser-framework-internals.md; continue the next bi- or fw- module; verify all Chromium paths, commands and class names against current upstream before relying on them, and log the result in PROGRESS.md §7.

Framework implementation: teach the conceptual model, implement a minimal version, then compare against production source. Never start from production source.

Application/platform work: work from frontend-principal-engineering.md; use the internals track only when underlying behaviour materially affects the topic.