Conventions

How future lessons are written and shipped in this repo.

File layout

Writing a new lesson

1. Add pages/lessons/NN-slug.mdx (zero-padded number).
2. Register it in pages/lessons/_meta.json for sidebar order.
3. Update curriculum.json (completed / next_lesson / upcoming).
4. Link it from the home curriculum table.
5. Prefer a PNG in public/ and a Mermaid overview in the MDX.

Diagram rules

• No ASCII architecture diagrams in new lessons — use Mermaid (```mermaid fences) and/or PNGs.
• Prefer images + Mermaid together: PNG for the rich illustration; Mermaid for the quick structural read and diffability.
• Keep PNG filenames stable so links don’t rot (hyperscale-fleet-topology.png, k8s-control-plane-at-scale.png, …).
• With basePath: '/hyperscale-prep', reference images as /hyperscale-fleet-topology.png (Next/Nextra prefixes basePath for public/ assets in MDX <img> / markdown images depending on setup — prefer markdown ![alt](/hyperscale-fleet-topology.png)).

Lesson shape (required sections)

Every lesson should include, in roughly this order:

1. What interviewers are really probing (operator view, not textbook)
2. Core diagram (PNG + Mermaid + “read it top-down”)
3. Idiosyncrasies you only learn in production
4. Concrete commands & config
5. Failures & fixes table — symptom → likely root cause → fix / mitigation
6. Security & hardening — dedicated, required (not optional); concrete controls + AI/ML angle when relevant
7. Interview soundbites
8. How this maps to the JD
9. Watch (talks & demos) — required when good public talks exist (see below)
10. References (real URLs)
11. Quick self-check

Security emphasis

Every lesson must stress hardening as operator work, not a bolted-on appendix. Put concrete controls (RBAC, network segmentation, short-lived creds, admission, origin lock-down, etc.) in the dedicated Security & hardening section after Failures & fixes.

AI/ML platform lessons must explicitly cover model weights, checkpoints, container images, and deployment provenance:

• Private registries; signed images / provenance (cosign / SLSA mindset); no unsigned deploy to prod
• Bucket IAM + encryption for weights/checkpoints; no world-readable object stores
• Least privilege to pull artifacts; scan / SBOM posture on runtime and base images
• Inference/training deployments: admission gates, network policy, secrets hygiene, GPU pool isolation

The Watch section remains required when applicable (KubeCon / re:Invent / CNCF talks).

Voice

• First-person operator experience is fine (“I have chased…”).
• Prefer production failure stories over certification checklists.
• Commands are illustrative — adapt to your cloud and security posture.
• When refreshing a lesson, keep the original date and note refreshed YYYY-MM-DD.

Local preview

npm install
npm run dev
# open http://localhost:3000/hyperscale-prep/

Static export (what GitHub Pages serves):

npm run build
# output in out/

Mermaid gotchas (v10)

• Never put | inside cylinder/stadium shapes — use "etcd 3 or 5" not [(etcd 3|5)].
• Quote node labels that contain /, %, :, or <br/>.
• Prefer ASCII hyphens over en-dashes (1-2 not 1–2).
• Decision nodes: ID{"label"} (quoted).
• Avoid Unicode arrows (→) in labels/messages — use then / to.

AI/ML platform track

In addition to the hyperscale JD arc, lessons also pull platform-engineering themes from wafer-ai/gpu-perf-engineering-resources (opens in a new tab): GPU fleets, topology (NVLink/RDMA/NCCL), gang/queue scheduling, inference serving SLOs (TTFT/TPOT/KV cache), and disaggregated serving — framed for operators who run the fabric, not for writing CUDA kernels from scratch. Pair that with Security emphasis: weights, checkpoints, images, and inference endpoints are first-class hardening targets.

Watch sections (YouTube)

Every lesson should include a Watch (talks & demos) section before References when good public talks exist:

• Prefer KubeCon, re:Invent, Google TechTalks / GOTO, CNCF channel recordings.
• Embed with a YouTube iframe (youtube.com/embed/VIDEO_ID) and a plain “Open on YouTube” link.
• 1–3 videos max; each needs a one-line “why watch” tied to the lesson (not a random dump).
• Skip rather than pad with low-signal content.