master practice guide · milestone-mapped edition

ONE MILESTONE
ONE EXERCISE

A direct companion to the technology guides. Every section uses the exact milestone order from its source guide, and every milestone has one primary exercise, two follow-up drills, and a narrow reference when the concept still is not sticking.

Mapping rule: milestone 01 → exercise 01, milestone 02 → exercise 02, and so on. No regrouping by project phase and no substitute concepts.

Graphics + Systems · 12 milestones

Godot + GDShader

One exercise for every milestone, in the same order and wording

Milestone 01 · exact map

3D scene setup — nodes and their roles

Source milestone

Set up a 3D scene: MeshInstance3D, Camera3D, WorldEnvironment — understand what each node's job is

Primary exercise

Create a 3D scene from scratch. Add a MeshInstance3D with a SphereMesh, a Camera3D pointing at it, and a WorldEnvironment with a sky. Run it. Then rename every node to something descriptive and write a one-line comment in a GDScript attached to the root explaining what each child does.

Follow-up 1Delete the Camera3D and try to run it. Read the error. Add it back in a different position and adjust its rotation so the sphere is still centered in view.

Follow-up 2Add a second MeshInstance3D with a BoxMesh. Position them side by side. Practice navigating the scene tree to select each one independently.

Still stuck?

Godot Docs — 3D scene introduction. Search 'your first 3D game' in the docs.

Milestone 02 · exact map

First fragment shader — UV coordinates

Source milestone

Attach a ShaderMaterial and write a fragment shader that colors by UV coordinates

Primary exercise

Attach a ShaderMaterial to your sphere. Write a fragment shader that sets ALBEDO to vec3(UV, 0.0). Run it. Draw on paper what you expect the colors to be before you run it, then compare. Change it to vec3(UV.x, 0.0, 0.0) and predict the result before running.

Follow-up 1Set ALBEDO to vec3(fract(UV * 5.0), 0.0) — predict what happens to the pattern before running. What does fract do and why does multiplying UV create repetition?

Follow-up 2Flip the UV vertically: vec3(UV.x, 1.0 - UV.y, 0.0). Then flip horizontally. Write down what operation you'd use to rotate UV 90 degrees.

Still stuck?

The Book of Shaders chapter 1–2. Godot shading language docs — search 'UV'.

Milestone 03 · exact map

Per-vertex vs per-fragment distinction

Source milestone

Understand the difference between what runs per-vertex and what runs per-fragment

Primary exercise

Write a shader with both a vertex() and fragment() function. In vertex(), add a small offset to VERTEX.y based on VERTEX.x — this deforms the mesh. In fragment(), color by UV. Run it and observe which stage controls shape vs color. Then try moving the color logic into vertex() via a varying — does it look different? Why?

Follow-up 1Create a varying float v_height and set it to VERTEX.y in vertex(). Use it in fragment() to tint the top of the mesh differently from the bottom. This is how you pass per-vertex data to the fragment stage.

Follow-up 2Move an expensive calculation (like a sine wave) from fragment() to vertex() and observe the visual difference. Write a note on why fragment() is more expensive than vertex().

Still stuck?

Book of Shaders chapter 3. Search 'varying' in the Godot shading language docs.

Milestone 04 · exact map

Uniforms driven from a GDScript

Source milestone

Use TIME and uniforms to animate shader parameters driven from a GDScript

Primary exercise

Add a uniform float brightness = 1.0 to your shader. In fragment(), multiply ALBEDO by brightness. Attach a GDScript to the MeshInstance3D. In _ready(), get the ShaderMaterial and set the brightness uniform to 2.0. Confirm the sphere is brighter. Then in _process(), oscillate brightness with sin(Time.get_ticks_msec() * 0.001).

Follow-up 1Add a uniform vec3 tint_color = vec3(1.0). Multiply ALBEDO by tint_color. Drive it from a script that cycles through red, green, blue over time.

Follow-up 2Add a UI slider to the scene. Connect its value_changed signal to a function that sets the brightness uniform. You now have a live parameter control.

Still stuck?

Godot docs — search 'ShaderMaterial set_shader_parameter'. GDScript signals docs.

Milestone 05 · exact map

Diffuse and specular lighting by hand

Source milestone

Implement diffuse and specular lighting by hand in the fragment stage — no built-in lighting nodes

Primary exercise

On a flat PlaneMesh, implement Lambertian diffuse from scratch. You need: the surface normal (NORMAL), a hardcoded light direction vec3, and the dot product between them clamped to 0. Set ALBEDO to vec3(diffuse). No engine lighting nodes. Then add a hardcoded light color and multiply it in.

Follow-up 1Add Blinn-Phong specular. You need: the view direction (VIEW), the halfway vector between light and view, and a shininess exponent. Add it on top of your diffuse.

Follow-up 2Make both the light direction and color uniforms driven from a script. Move the light direction in a circle using sin/cos in _process().

Still stuck?

Book of Shaders chapter 5. Search 'Phong lighting model' on learnopengl.com — the math is identical even though it's OpenGL.

Milestone 06 · exact map

MVP matrix — what each transform does

Source milestone

Understand the MVP matrix: what model, view, and projection each do to a vertex

Primary exercise

In a vertex shader, print MODELVIEW_MATRIX and PROJECTION_MATRIX to understand what's available. Then manually break the pipeline: multiply VERTEX by only the model matrix (MODEL_MATRIX * vec4(VERTEX, 1.0)) and assign to POSITION — observe what happens. Restore it. Write a note explaining what each matrix's job is in one sentence each.

Follow-up 1Offset VERTEX by vec3(1.0, 0.0, 0.0) before any matrix multiplication. Then offset it after multiplying by MODEL_MATRIX. Observe the difference — one is object space, one is world space.

Follow-up 2Scale VERTEX by 2.0 in the vertex stage vs scaling the node's transform in the editor. Write down why these produce different results.

Still stuck?

learnopengl.com — 'Coordinate Systems' chapter. Direct mapping to Godot's matrix uniforms.

Milestone 07 · exact map

Vertex deformation with noise

Source milestone

Deform geometry in the vertex stage — displace vertices with a noise function

Primary exercise

On a PlaneMesh with enough subdivisions (at least 32x32), displace VERTEX.y in the vertex stage using a sin wave: VERTEX.y += sin(VERTEX.x * 3.0 + TIME) * 0.2. Run it. Then replace the sin wave with a more complex noise pattern by combining two sin waves with different frequencies.

Follow-up 1Pass the deformed height as a varying into fragment() and use it to color the mesh — peaks one color, valleys another.

Follow-up 2Add a uniform float wave_speed and uniform float wave_height driven from a script. Make the wave parameters live-adjustable.

Still stuck?

Book of Shaders chapter 5 — noise. Godot docs — 'vertex() built-in variables'.

Milestone 08 · exact map

SubViewport as a render target

Source milestone

Use SubViewport as a render target — render a scene into a texture, use that texture in another shader

Primary exercise

Create a SubViewport node with its own Camera3D and a rotating mesh inside it. Add a ViewportTexture referencing this SubViewport to a material on a quad in your main scene. You are now rendering one scene into a texture and displaying that texture in another scene. Confirm it works — the quad should show the rotating mesh.

Follow-up 1Apply a shader to the quad that distorts the ViewportTexture using UV warping. You're now post-processing a render in real time.

Follow-up 2Add a second SubViewport that renders the same scene from a different camera angle. Display both on two quads side by side.

Still stuck?

Godot docs — 'Using a Viewport as a texture'. Search 'ViewportTexture'.

Milestone 09 · exact map

Compute shader via RenderingDevice — dispatch and readback

Source milestone

Write a compute shader via RenderingDevice — dispatch a workgroup, write to a buffer, read it back

Primary exercise

Write a compute shader that doubles every value in a float array. On the CPU side: create a RenderingDevice, create a storage buffer with [1.0, 2.0, 3.0, 4.0], dispatch 4 threads (one per element), read the buffer back, print the result. Confirm you get [2.0, 4.0, 6.0, 8.0]. This proves the pipeline works before you make it complex.

Follow-up 1Change the compute shader to square each value instead of double it. Confirm the output.

Follow-up 2Increase the array to 1024 elements, generate them procedurally on the CPU, dispatch 1024 threads, and time how long the GPU operation takes vs doing it in GDScript.

Still stuck?

Godot docs — 'Using compute shaders'. Search 'RenderingDevice' in the docs.

Milestone 10 · exact map

GPU particle system via compute

Source milestone

Build a GPU particle system: particle state lives in a storage buffer, updated entirely by compute

Primary exercise

Define a particle struct in your compute shader with position (vec2), velocity (vec2), and lifetime (float). Store N particles in a storage buffer. Each dispatch call: move position by velocity, decrement lifetime, respawn if lifetime <= 0. On the CPU: initialize particles, dispatch each frame, render positions as points using immediate geometry or a shader.

Follow-up 1Add a gravity force (subtract from velocity.y each frame) in the compute shader. Adjust the respawn position to be a point emitter.

Follow-up 2Add a color that fades from white to transparent as lifetime decreases. Pass color through the buffer alongside position.

Still stuck?

Acerola on YouTube — search 'compute shader particles'. Godot RenderingDevice docs.

Milestone 11 · exact map

Multi-pass pipeline — geometry into lighting into post

Source milestone

Implement a multi-pass pipeline: geometry pass → lighting pass → post-processing stack

Primary exercise

Set up three SubViewports in sequence. Viewport 1: renders your scene normally into a texture. Viewport 2: takes that texture as input, applies a grayscale conversion in a fragment shader, outputs to another texture. Viewport 3: takes viewport 2's output and applies a vignette. Display the final result. Confirm each pass is doing what you expect by temporarily displaying each intermediate texture.

Follow-up 1Replace the grayscale pass with a blur — average the surrounding 9 pixels. Adjust the blur radius with a uniform.

Follow-up 2Add a bloom pass: threshold bright pixels, blur them, add back to the original. This is the core of every bloom implementation.

Still stuck?

Acerola on YouTube — search 'post processing'. Godot docs 'multiple render targets'.

Milestone 12 · exact map

What Godot is abstracting from you

Source milestone

Understand what Godot is abstracting from you that Vulkan would force you to manage explicitly

Primary exercise

Write a list of at least five things Godot handles that you would have to manage manually in raw Vulkan. For each one, write a sentence describing what the manual version would require. Examples to get you started: swap chain management, render pass creation, pipeline state objects. This is a thinking exercise, not a coding one.

Follow-up 1Look up one item from your list in the Vulkan tutorial (vulkan-tutorial.com). Read just the section that covers it. How many lines of code does Godot save you for that one thing?

Follow-up 2Identify which of the things on your list you want to understand at the Vulkan level and which you're comfortable leaving abstracted. This shapes what you tackle after the Godot phase.

Still stuck?

vulkan-tutorial.com — skim the 'Drawing a triangle' section to feel the contrast. No need to implement it yet.

Graphics + Systems · 14 milestones

C++

One exercise for every milestone, in the same order and wording

Milestone 01 · exact map

Stack vs heap — what lives where

Source milestone

Understand the stack and heap: what lives where, why it matters, and what a stack frame is

Primary exercise

Write a function that declares an int on the stack and returns a pointer to it. Call it from main and print the value through the pointer. Observe that the value is garbage or seemingly correct but undefined. Fix it by allocating on the heap instead. Then fix it again using a return by value. Write a comment explaining why each version behaves as it does.

Follow-up 1Draw the stack on paper during three nested function calls. Show what each frame contains and what happens to the memory when each function returns.

Follow-up 2Write a program that exhausts the stack with infinite recursion. Run it. Observe the stack overflow. Add a base case to fix it.

Still stuck?

learncpp.com — 'Stack and Heap Memory'. Chapter 12.

Milestone 02 · exact map

Pointers, references, and dangling pointers

Source milestone

Pointers and references: when to use each, what a dangling pointer looks like, and how to avoid one

Primary exercise

Write four versions of a function that increments an integer: taking by value, by pointer, by reference, and returning a new value. Call each from main and confirm which ones actually modify the original. Then write a function that returns a reference to a local variable — compile with warnings enabled and read what the compiler tells you.

Follow-up 1Write a program that creates a pointer, deletes it, then dereferences it. Run it multiple times. Observe that it sometimes crashes, sometimes gives garbage, sometimes seems to work — this is undefined behavior in action.

Follow-up 2Write the same pointer program but set the pointer to nullptr after deleting it, then check for nullptr before dereferencing. This is the manual version of what smart pointers automate.

Still stuck?

learncpp.com — 'Introduction to Pointers' and 'Dangling Pointers'. A Tour of C++ chapter 1.

Milestone 03 · exact map

RAII — constructor acquires, destructor releases

Source milestone

RAII: why resource acquisition in the constructor and release in the destructor is the correct model

Primary exercise

Write a FileHandle class. The constructor takes a filename string and opens the file with fopen. The destructor calls fclose. Delete the copy constructor and copy assignment operator. Use it in a function that opens a file, reads one line, and returns — confirm the file is closed when the function returns by adding a print to the destructor.

Follow-up 1Throw an exception inside the function after opening the file. Confirm the destructor still runs and the file is still closed. This is the core guarantee RAII provides.

Follow-up 2Write the same file-reading function without RAII using raw FILE* and manual fclose. Add four different early-return paths. Notice how many places you have to remember to call fclose.

Still stuck?

learncpp.com — 'Introduction to RAII'. A Tour of C++ chapter 5.

Milestone 04 · exact map

Rule of 0/3/5

Source milestone

Rule of 0/3/5: when the compiler-generated versions are wrong and what to write instead

Primary exercise

Write a Buffer class that holds a raw int* allocated in the constructor. Write a main that copies one Buffer to another (Buffer b2 = b1). Run it and observe what happens when both destructors run. Fix it by implementing the rule of 3: a destructor, copy constructor, and copy assignment operator that each do the right thing. Then add move semantics (rule of 5) and confirm the move leaves the source in a valid empty state.

Follow-up 1Remove all five and replace them with a single std::vector<int> member. Observe that the compiler-generated versions all work correctly now. This is the rule of 0 — if you use types that manage their own resources, you don't write any of them.

Follow-up 2Write a class that intentionally violates the rule of 3 — has a destructor but no copy constructor. Pass it to a function by value. Observe the double-free crash.

Still stuck?

learncpp.com — 'The Rule of Three/Five/Zero'. A Tour of C++ chapter 6.

Milestone 05 · exact map

Smart pointers — unique_ptr, shared_ptr, weak_ptr

Source milestone

Smart pointers: unique_ptr for single ownership, shared_ptr for shared ownership, weak_ptr for observation

Primary exercise

Rewrite your Buffer class exercise using unique_ptr<int[]> instead of a raw pointer. Observe that you don't need to write the destructor, copy constructor, or copy assignment — they're automatically correct. Then try to copy the unique_ptr and read the compile error. Fix it with std::move and observe that the source is now null.

Follow-up 1Create two classes that hold shared_ptr to each other. Confirm the memory leaks by adding print statements to each destructor — they never fire. Fix one direction with weak_ptr and confirm the destructors now run.

Follow-up 2Write a factory function that returns a unique_ptr. Assign the result to a raw pointer in main by calling .release(). Manually delete the raw pointer. This shows you the escape hatch from smart pointers and why you avoid it.

Still stuck?

learncpp.com — 'Smart Pointers'. A Tour of C++ chapter 13.

Milestone 06 · exact map

Move semantics — what a move actually does

Source milestone

Move semantics: what a move actually does at the memory level and why it matters for performance

Primary exercise

Write a class with a constructor, destructor, copy constructor, move constructor, and print statements in each. Create an instance, copy it, move it. Read the output and trace exactly which operations fired. Then write a function that returns an instance of your class and observe whether a copy or move fires (or neither, due to RVO).

Follow-up 1Write a vector-like container that holds a unique_ptr<int[]>. Try to put it in a std::vector. Observe the error. Fix it by implementing a move constructor. Now std::vector can resize without copying.

Follow-up 2Mark your move constructor as noexcept. Put your type in a std::vector and call push_back enough times to trigger a reallocation. Confirm the move constructor fires instead of the copy constructor.

Still stuck?

learncpp.com — 'Move Semantics'. A Tour of C++ chapter 6.

Milestone 07 · exact map

Classes, virtual dispatch, and the vtable

Source milestone

Classes, inheritance, and virtual dispatch: what the vtable is and what it costs

Primary exercise

Write a Shape base class with a virtual float area() method. Derive Circle and Rectangle from it. Store both in a vector<Shape*> and call area() through the base pointer. Confirm polymorphism works. Then add a non-virtual method to Shape and override it in Circle — call it through a Shape* and observe that the base version runs. Write a comment explaining why.

Follow-up 1Add a virtual destructor to Shape. Remove it. Create a Circle on the heap, store it as Shape*, delete through the base pointer. Observe what happens without the virtual destructor. Add it back.

Follow-up 2Use sizeof on your Shape and Circle classes with and without the virtual method. Observe the vtable pointer being added to the object size.

Still stuck?

learncpp.com — 'Virtual Functions'. A Tour of C++ chapter 4.

Milestone 08 · exact map

Templates and the STL

Source milestone

Templates and the STL: vector, map, unordered_map, iterators, algorithms — use them, don't rewrite them

Primary exercise

Write a generic min function template that works for int, float, and std::string. Then use std::sort on a vector<int> with the default comparator, then with a custom lambda that sorts in reverse. Then use std::find_if to find the first element greater than 5. Write a note on what the algorithm is doing and what the iterator abstraction is giving you.

Follow-up 1Write a template Stack<T> class backed by a std::vector<T>. Implement push, pop, top, and empty. Instantiate it with int and with std::string.

Follow-up 2Use std::transform to double every element in a vector<int> into a new vector. Then use std::accumulate to sum the result. Do the same thing with a raw loop and compare the code.

Still stuck?

learncpp.com — 'Templates' and 'Standard Library Containers'. A Tour of C++ chapters 8–9.

Milestone 09 · exact map

const-correctness

Source milestone

const-correctness: what it means for a method to be const and why it matters

Primary exercise

Write a Point class with x and y members and a toString() method. Compile this: const Point p{1, 2}; std::cout << p.toString(); — observe the error. Fix it by marking toString() as const. Then write a function that takes a const Point& and calls a non-const method on it. Fix that too. Write a note on what const on a method guarantees.

Follow-up 1Write a class with a mutable int call_count member. Mark a method const but increment call_count inside it. Confirm it compiles — mutable is the escape hatch from const.

Follow-up 2Write a function that returns both a const and non-const reference to the same data (two overloads). Call each from a const and non-const context and observe which overload fires.

Still stuck?

learncpp.com — 'Const class objects and member functions'.

Milestone 10 · exact map

Build systems — CMake, translation units, linking

Source milestone

Build systems: what CMake does, what a compilation unit is, how linking works

Primary exercise

Create a CMakeLists.txt that builds a two-file project: main.cpp and math.cpp, with math.h as the header. Define an add function in math.cpp, declare it in math.h, include the header in main.cpp, call the function. Build it with cmake and make. Then deliberately create a linker error by removing math.cpp from the CMakeLists.txt and read the error message.

Follow-up 1Add a third file utils.cpp. Create a circular include: math.h includes utils.h and utils.h includes math.h. Observe the error. Fix it with include guards (#pragma once or #ifndef guards).

Follow-up 2Move the add function definition into the header file. Observe the multiple definition linker error when two .cpp files include it. Fix it with the inline keyword.

Still stuck?

learncpp.com — 'Introduction to the compiler, linker, and libraries'. CMake docs tutorial.

Milestone 11 · exact map

Multithreading — threads, mutex, atomics

Source milestone

Multithreading: std::thread, mutex, atomic — what a data race looks like and how to prevent one

Primary exercise

Write a program that increments a shared int counter 1,000,000 times across two threads without any synchronization. Run it multiple times and record the results — they should vary. Then add a std::mutex and lock it around the increment. Run again — the result should now always be 2,000,000. Finally replace the mutex with std::atomic<int> and compare the performance.

Follow-up 1Introduce a deadlock: two mutexes, two threads, each locking them in opposite order. Confirm the program hangs. Fix it by always locking in the same order, or using std::lock.

Follow-up 2Write a producer-consumer using std::queue, a std::mutex, and a std::condition_variable. Producer pushes items, consumer pops and processes them.

Still stuck?

learncpp.com — 'Introduction to threads'. A Tour of C++ chapter 18.

Milestone 12 · exact map

Undefined behavior — causes and reasoning

Source milestone

Undefined behavior: the three most dangerous causes and how to reason about them

Primary exercise

Write three programs that each contain a different form of undefined behavior: (1) out-of-bounds array access, (2) signed integer overflow, (3) reading an uninitialized variable. Compile each with and without -fsanitize=address,undefined. Observe what the sanitizers catch that a plain run might not. Write a comment on each explaining why the behavior is undefined rather than defined as an error.

Follow-up 1Write a program where UB causes a visibly wrong result rather than a crash — for example, a loop that the compiler optimizes away because it relies on signed overflow being impossible. Read the assembly output with -O2.

Follow-up 2Enable all compiler warnings (-Wall -Wextra -Wpedantic) on your existing projects. Fix every warning. Note which warnings correspond to UB you'd already written.

Still stuck?

learncpp.com — 'Undefined behavior'. Search 'UB and compiler optimizations' for the deeper rabbit hole.

Milestone 13 · exact map

Graphics pipeline from C++ — draw call to pixels

Source milestone

The graphics pipeline from C++: how a draw call gets from your code to pixels — buffers, shaders, the GPU driver

Primary exercise

In a minimal OpenGL or Vulkan setup (learnopengl.com has the scaffold), trace a single triangle from definition to pixels: define vertices in a C++ array, upload to a VBO, write a minimal vertex shader that passes position through, write a minimal fragment shader that outputs red, issue a draw call, observe the red triangle. Comment each step with what layer of the pipeline it corresponds to.

Follow-up 1Add a uniform mat4 to the vertex shader. Set it from C++ using glUniformMatrix4fv. Pass an identity matrix first, then a translation matrix, and observe the triangle moving.

Follow-up 2Add a second triangle with a different color using a second draw call vs the same draw call with an index buffer. Observe the difference in how many GPU calls you're making.

Still stuck?

learnopengl.com — 'Hello Triangle'. This is the primary resource for this milestone.

Milestone 14 · exact map

Low-level I/O — binary data and hardware

Source milestone

Low-level I/O: reading and writing binary data, talking to hardware at the byte level

Primary exercise

Write a program that reads a BMP or WAV file in binary mode (fopen with 'rb'). Parse the header manually by casting the raw bytes into a struct. Print the width, height, and bit depth (BMP) or sample rate and channel count (WAV). Write the raw pixel or sample data back out to a new file. Confirm the output file is valid.

Follow-up 1Write a minimal binary serialization system: a struct with several fields, a function that writes it to a file as raw bytes, a function that reads it back. Confirm round-trip correctness.

Follow-up 2Write a program that memory-maps a file using mmap (Linux/Mac) or MapViewOfFile (Windows). Read a large file through the mapped pointer and measure the performance vs fread.

Still stuck?

learncpp.com — 'File I/O'. Search 'binary file I/O C++' for struct-level parsing examples.

Graphics + Systems · 09 milestones

Lua Embedding

One exercise for every milestone, in the same order and wording

Milestone 01 · exact map

Tables — array, map, and object simultaneously

Source milestone

Tables: the only data structure — understand how one table represents an array, a map, and an object simultaneously

Primary exercise

In the Lua REPL, create a table that functions as all three things at once: integer keys 1–3 (array part), string keys 'name' and 'age' (map part), and a function value 'greet' (object part). Access each one. Then iterate it with ipairs and pairs and write down what each iterator visits and what it skips.

Follow-up 1Write a function that takes any table and prints every key-value pair regardless of key type. Observe that ipairs stops at the first nil — use pairs instead.

Follow-up 2Create a table where the array and map parts share the same table. Add integer key 1 via array syntax and string key '1' via map syntax. Are they the same key? Test it.

Still stuck?

Programming in Lua chapter 2 — Tables.

Milestone 02 · exact map

Functions as first-class values and closures

Source milestone

Functions as first-class values: closures, upvalues, and why functions in Lua are just values

Primary exercise

Write a make_counter function that returns a function. Each call to the returned function increments and returns a count. Create two counters and confirm they maintain independent state. Write a comment explaining what the closure is capturing and why each counter is independent.

Follow-up 1Write a function factory that takes a multiplier and returns a function that multiplies its argument by that multiplier. Create times2 and times3 from it.

Follow-up 2Store three different functions in a table keyed by string name. Call each one by looking up the key. This is the pattern used for command dispatch and event systems.

Still stuck?

Programming in Lua chapter 6 — Closures.

Milestone 03 · exact map

Metatables and __index — OOP and inheritance

Source milestone

Metatables and __index: how Lua fakes OOP and inheritance without a class keyword

Primary exercise

Build a minimal class system. Write a function new_class() that returns a class table with a new() method. new() should create an instance table whose metatable's __index points to the class — so instances inherit class methods. Add a method greet to the class. Create two instances and confirm they both have access to greet without it being copied onto each instance.

Follow-up 1Extend the class system to support inheritance: new_class(Parent) where the child's __index chain falls through to the parent if a key isn't found on the child.

Follow-up 2Add an __tostring metamethod to your class so print(instance) shows something useful. Then add __eq so two instances with the same name field compare as equal.

Still stuck?

Programming in Lua chapter 16 — OOP. Chapter 13 — Metatables.

Milestone 04 · exact map

Coroutines — yield and resume

Source milestone

Coroutines: cooperative multitasking, yield and resume, when they're useful vs threads

Primary exercise

Write a coroutine that generates Fibonacci numbers. Each call to coroutine.resume should yield the next number. Call it 10 times from a loop and collect the results. Then write a note explaining why this is different from calling a function 10 times — what state is being preserved between resumes?

Follow-up 1Write two coroutines that take turns — coroutine A prints 'ping' then resumes B, B prints 'pong' then resumes A. Run 5 exchanges manually with resume calls from main.

Follow-up 2Write a coroutine-based iterator: a function that wraps a coroutine in a closure so it can be used in a for loop. Iterate a range of numbers with it.

Still stuck?

Programming in Lua chapter 9 — Coroutines.

Milestone 05 · exact map

Multiple return values and varargs

Source milestone

Multiple return values and varargs: patterns that don't exist in most languages

Primary exercise

Write a function that returns three values: the min, max, and average of a table of numbers. Call it and capture all three return values. Then write a wrapper that takes varargs (...), packs them into a table with table.pack, and passes the table to your min/max/average function.

Follow-up 1Write a function that returns a different number of values depending on a condition. Call it and observe what happens when you capture more return values than the function returned.

Follow-up 2Write a printf-style function in Lua using varargs and string.format. Call it with different argument counts.

Still stuck?

Programming in Lua chapter 5 — Functions.

Milestone 06 · exact map

The C API stack model — pushing and popping

Source milestone

The C API stack model: how Lua and C exchange values by pushing and popping a shared stack

Primary exercise

In a minimal C program with Lua embedded, write a C function that takes two numbers from the Lua stack, adds them, and pushes the result back. Register it as 'add' in Lua. Call it from a Lua script: assert(add(3, 4) == 7). Print the stack size before and after your operations to confirm you're leaving it clean.

Follow-up 1Write a C function that takes a Lua table as its argument. Iterate the table from C using lua_next and print each key-value pair. This is how you read Lua data from the host.

Follow-up 2Write a C function that creates a new Lua table, populates it with three key-value pairs from C, and returns it to Lua. Confirm Lua can access all three values.

Still stuck?

Programming in Lua chapter 27 — The C API. Lua reference manual — lua_State and stack operations.

Milestone 07 · exact map

Registering C functions for Lua to call

Source milestone

Registering a C function so Lua scripts can call into your C++ host

Primary exercise

Register at least three C functions into a Lua namespace: engine.log(msg), engine.get_time(), and engine.set_color(r, g, b). Call all three from a Lua script. Confirm each one runs. Then register them as a library using luaL_newlib rather than setting globals one by one.

Follow-up 1Register a C function that accepts optional arguments — use lua_isnumber with a default fallback for missing args. Call it with and without the optional argument from Lua.

Follow-up 2Register a C function that returns multiple values to Lua. Capture all of them on the Lua side and confirm they arrived correctly.

Still stuck?

Programming in Lua chapter 28 — Extending Lua. Lua reference manual — luaL_newlib.

Milestone 08 · exact map

Calling a Lua function from C++

Source milestone

Calling a Lua function from C++: loading a script, pushing arguments, calling, reading results

Primary exercise

Load a Lua script from a file that defines a function behavior(x, y) which returns x * 2 + y. From C++: open a Lua state, load the file, push the function name, push two numbers as arguments, call it with lua_pcall, and read the return value off the stack. Print it. Change the Lua file and rerun without recompiling C++.

Follow-up 1Wrap the lua_pcall call in a C++ function template that takes a function name, arguments, and returns a typed result. This is the beginning of a scripting API.

Follow-up 2Call a Lua function that itself calls back into a registered C function. Confirm the round-trip: C++ calls Lua calls C++ calls Lua. Trace the call stack on paper.

Still stuck?

Programming in Lua chapter 25 — Calling Lua functions from C. Lua reference manual — lua_pcall.

Milestone 09 · exact map

Embedding the Lua interpreter in C++

Source milestone

Embedding the Lua interpreter in a C++ program: luaL_newstate, opening libs, loading files

Primary exercise

Write a complete minimal embedding: luaL_newstate, luaL_openlibs, load a script with luaL_dofile, run it, close with lua_close. The script should print 'hello from Lua'. Then extend it: the script defines a config table, your C++ code reads three values from it using lua_getglobal and lua_getfield. Print them from C++.

Follow-up 1Add error handling: wrap luaL_dofile in a check, print the error message from the stack if it fails. Test it by introducing a syntax error in the Lua file.

Follow-up 2Load and execute a Lua script that itself requires another Lua file. Confirm Lua's require system works correctly inside your embedding.

Still stuck?

Programming in Lua chapter 24 — An Overview of the C API. Lua reference manual — luaL_newstate.

Web Application Pair · 12 milestones

TypeScript + Vue

One exercise for every milestone, in the same order and wording

Milestone 01 · exact map

What TypeScript adds — the compiler's job

Source milestone

Understand what TypeScript adds over JavaScript — what the compiler catches and why that matters

Primary exercise

Write a function greet(name) in plain JavaScript and call it with a number. It works. Now add TypeScript types: greet(name: string): string. Call it with a number. Read the error. Then introduce an intentional type mismatch in a variable assignment and read that error. Write down in plain English what the compiler caught and why JavaScript wouldn't have.

Follow-up 1Find three places in a JavaScript project (or write a small one) where TypeScript would catch a bug that would be a runtime error in plain JS. Convert those three functions to TypeScript.

Follow-up 2Turn off strict mode in tsconfig. Observe which errors disappear. Turn it back on. Write a note on what strict mode is actually checking.

Still stuck?

TypeScript Handbook — 'The Basics'. typescriptlang.org/docs/handbook/2/basic-types.html

Milestone 02 · exact map

Types, interfaces, unions, and type aliases

Source milestone

Core types: string, number, boolean, arrays, tuples, and the difference between type and interface

Primary exercise

Write a type alias for a UserId (string). Write an interface for a User with id, name, email, and an optional age. Write a union type Status = 'active' | 'inactive' | 'pending'. Write a function that takes a User and returns a Status. Then write a second interface AdminUser that extends User with a permissions string array.

Follow-up 1Write a discriminated union: type Shape = { kind: 'circle', radius: number } | { kind: 'rect', width: number, height: number }. Write an area function that switches on kind and confirm TypeScript knows which fields are available in each branch.

Follow-up 2Write the same structures with type instead of interface. Find one thing you can do with type that you can't do with interface and one thing vice versa.

Still stuck?

TypeScript Handbook — 'Object Types' and 'Union Types'.

Milestone 03 · exact map

Type narrowing

Source milestone

Union types and type narrowing — how TypeScript knows what something is inside a conditional

Primary exercise

Write a function that takes string | number. Inside it, use typeof to narrow to each branch and perform a type-specific operation (toUpperCase for string, toFixed for number). Then write a function that takes an Animal interface and a Dog interface that extends it — use the 'in' operator to narrow to Dog and access a dog-specific property.

Follow-up 1Write a type guard function isString(value: unknown): value is string. Use it in a narrowing check and confirm TypeScript trusts the narrowed type inside the conditional.

Follow-up 2Write a function that takes unknown as a parameter. Narrow it through typeof, Array.isArray, and an instanceof check to safely access nested properties.

Still stuck?

TypeScript Handbook — 'Narrowing'.

Milestone 04 · exact map

Optional chaining and null handling

Source milestone

Optional chaining and nullish coalescing — handling null and undefined without explosion

Primary exercise

Create a nested object type: User with an optional address, address with an optional city. Create instances where address is present, where it's undefined, and where address exists but city is undefined. Access city safely using optional chaining for all three. Then use nullish coalescing to provide a 'Unknown City' default.

Follow-up 1Write a function that accepts User | null | undefined. Return the city or a default using optional chaining and nullish coalescing in a single expression.

Follow-up 2Enable strictNullChecks in tsconfig. Take an existing function that doesn't handle null and observe how many errors appear. Fix them all.

Still stuck?

TypeScript Handbook — 'Everyday Types' — null and undefined section.

Milestone 05 · exact map

Generics at a working level

Source milestone

Generics at a working level — read and write generic functions without needing the deepest corners

Primary exercise

Write a generic identity function <T>(value: T): T. Call it with a string, a number, and an object. Observe the inferred types. Then write a generic first<T>(arr: T[]): T | undefined that returns the first element of any array. Write a generic Pair<A, B> type and a function that swaps the two values.

Follow-up 1Add a constraint: write a function <T extends { length: number }>(value: T): number that returns the length of anything that has a length property. Call it with strings, arrays, and a custom object.

Follow-up 2Write a generic Result<T, E> type: either { ok: true, value: T } or { ok: false, error: E }. Write a function that returns Result<number, string> and handles both branches at the call site.

Still stuck?

TypeScript Handbook — 'Generics'.

Milestone 06 · exact map

Async/await and Promises

Source milestone

Async/await and Promises — the event loop mental model and how async functions compose

Primary exercise

Write three async functions that each resolve after a delay (use setTimeout wrapped in a Promise). Call them sequentially with await and measure the total time. Then call them with Promise.all and measure again. Write a comment explaining why Promise.all is faster and what it's doing differently.

Follow-up 1Write an async function that can fail. Wrap the await in a try/catch and handle both the success and error cases. Then write the same thing using .then().catch() chaining.

Follow-up 2Write a race between two promises with Promise.race — one resolves quickly, one resolves slowly. Confirm the fast one wins. Then observe what happens to the slow one.

Still stuck?

TypeScript Handbook — 'Everyday Types' async section. MDN — 'Using Promises'.

Milestone 07 · exact map

Fetch and typed API responses

Source milestone

Fetch and typed API responses — model a REST response as an interface, type the data end to end

Primary exercise

Fetch data from https://jsonplaceholder.typicode.com/users. Write a User interface that matches the response shape. Assign the parsed response to User[] — no 'any'. Access user.name and user.email through the typed response. Then write a fetchUser(id: number): Promise<User> function that fetches a single user by ID.

Follow-up 1Add error handling: check response.ok before parsing JSON. Return a typed Result<User, string> instead of throwing. Handle both cases at the call site.

Follow-up 2Write a generic fetchJSON<T>(url: string): Promise<T> function. Use it to fetch both users and posts (different interfaces) with full type safety.

Still stuck?

TypeScript Handbook — 'Everyday Types'. MDN — Fetch API.

Milestone 08 · exact map

Vue single-file components — script setup, template, props

Source milestone

Vue single-file components — the <script setup>, <template>, and <style> structure and what each section does

Primary exercise

Create a UserCard.vue single-file component with <script setup lang="ts"> that accepts a User prop (your interface from above) and renders name, email, and age. Create a UserList.vue that accepts User[] as a prop and renders a UserCard for each with :key. Then write a HighlightCard.vue that wraps UserCard and adds a colored border prop — define both the User fields and the extra color string in defineProps.

Follow-up 1Use <slot> in a wrapper component to render whatever content is passed inside it. This is Vue's equivalent of children props — more explicit and more composable.

Follow-up 2Write a component that uses v-if and v-else to conditionally render based on a boolean prop. Then write the same logic using a computed ref that returns the display string. Note how Vue keeps conditional logic in the template vs in script.

Still stuck?

Vue docs — vuejs.org/guide/components/props and vuejs.org/guide/components/slots.

Milestone 09 · exact map

ref, reactive, and computed

Source milestone

ref and reactive — Vue's reactivity primitives, when to use each, and how computed() derives from them

Primary exercise

Write a counter component using <script setup lang="ts">. Use ref<number>(0) for the count. Add increment, decrement, and reset functions bound to buttons with @click. Then add a watch that logs the count whenever it changes. Then add a watchEffect that sets document.title to the current count. Observe that watchEffect runs immediately on mount without needing an explicit dependency list.

Follow-up 1Use onMounted and onUnmounted lifecycle hooks to set up and tear down an interval. Confirm the interval is cleared when the component is removed from the DOM by conditionally rendering it in a parent.

Follow-up 2Write a computed ref that derives a formatted string from the counter value. Observe that it updates automatically without any explicit dependency declaration — Vue tracks it for you.

Still stuck?

Vue docs — vuejs.org/guide/essentials/reactivity-fundamentals and vuejs.org/guide/essentials/watchers.

Milestone 10 · exact map

Loading, error, and success states with Vue composables

Source milestone

watchEffect and watch — reacting to reactive state changes, the equivalent of useEffect in Vue

Primary exercise

Write a Vue composable useUser(id: number) in a separate useUser.ts file. Inside it, use ref for the user data, a loading boolean ref, and an error ref. Fetch on call, set each ref appropriately. Return all three. Consume the composable in a component and render each state explicitly with v-if/v-else-if/v-else. Add a retry button that re-calls the fetch function.

Follow-up 1Add a watchEffect inside the composable that re-fetches whenever the id parameter changes. Pass id as a ref from the parent and observe the composable reacting automatically.

Follow-up 2Add an AbortController inside the composable. Cancel the in-flight request when the component using the composable is unmounted via the onUnmounted lifecycle hook.

Still stuck?

Vue docs — vuejs.org/guide/reusability/composables. TypeScript Handbook — discriminated unions.

Milestone 11 · exact map

Vite and build tooling

Source milestone

Vite as a build tool — what a bundler does, what npm scripts are, how modules resolve

Primary exercise

Create a new project with npm create vite@latest — choose React + TypeScript. Run it. Then inspect the vite.config.ts file and write a comment explaining what each option does. Add a path alias (e.g., @components maps to ./src/components). Import a component using the alias and confirm it resolves.

Follow-up 1Run npm run build and inspect the dist folder. Find the bundled JavaScript. Observe how Vite has split and minified your code. Add a console.log in a component and find it in the bundle.

Follow-up 2Add an environment variable in a .env file. Access it through import.meta.env in a component. Observe that it's type-safe only after you extend the ImportMeta interface.

Still stuck?

Vite docs — vitejs.dev/guide. TypeScript Handbook — 'Module Resolution'.

Milestone 12 · exact map

Props, emits, and typed component communication

Source milestone

Props and emits — passing typed data down, emitting typed events up, and when prop drilling becomes a problem

Primary exercise

Build a three-level component tree: App → UserList → UserCard. Pass a User[] down through typed props at each level using defineProps<{ users: User[] }>(). Add a select emit: in UserCard, use defineEmits<{ select: [user: User] }>() and emit it on click. Bubble it up through UserList to App where it's displayed. Count how many components the emit passes through unnecessarily.

Follow-up 1Replace the prop-drilling with Vue's provide/inject. provide the selected user ref at App level, inject it in UserCard. Observe how the intermediate UserList component no longer needs to know about it.

Follow-up 2Write a typed input handler: bind a ref<string> to an <input> with v-model and confirm Vue infers the string type. Then write a manual @input handler and type the Event parameter explicitly.

Still stuck?

Vue docs — vuejs.org/guide/components/provide-inject and vuejs.org/guide/components/events.

Web Application Pair · 10 milestones

One exercise for every milestone, in the same order and wording

Milestone 01 · exact map

Structs, methods, and Go's type system

Source milestone

Structs and methods — Go's type system without classes or inheritance

Primary exercise

Define a Rectangle struct with Width and Height float64 fields. Add an Area() method and a Perimeter() method on the value receiver. Add a Scale(factor float64) method on a pointer receiver. Create a rectangle, call all three methods. Write a comment explaining why Scale needs a pointer receiver and Area doesn't.

Follow-up 1Write a String() method on Rectangle that returns a formatted string. Call fmt.Println on a Rectangle and observe that Go automatically uses String() for display — this is the Stringer interface.

Follow-up 2Define a type Celsius float64 and a type Fahrenheit float64. Write conversion methods between them. Try to assign a Celsius value directly to a Fahrenheit variable and read the compile error.

Still stuck?

Tour of Go — 'Methods'. Go docs — 'Effective Go: Methods'.

Milestone 02 · exact map

Interfaces — implicit satisfaction

Source milestone

Interfaces — implicit satisfaction, how Go achieves polymorphism without explicit implements

Primary exercise

Write a Shape interface with Area() float64 and Perimeter() float64. Write a Circle and Rectangle type that both satisfy it without declaring 'implements Shape' anywhere. Store both in a []Shape slice and call Area() and Perimeter() through the interface. Then write a function that takes a Shape and prints both values — pass it both types.

Follow-up 1Write a type that satisfies multiple interfaces simultaneously. Confirm that a single method set can satisfy several interface requirements without any extra code.

Follow-up 2Use the empty interface (any / interface{}) to write a function that accepts anything. Then add a type assertion to extract a concrete type. Add a type switch to handle multiple types.

Still stuck?

Tour of Go — 'Interfaces'. A Tour of Go — 'Type assertions'.

Milestone 03 · exact map

Error handling — explicit returns

Source milestone

Error handling — explicit error returns, the error interface, when to wrap vs return raw

Primary exercise

Write a divide(a, b float64) (float64, error) function that returns an error when b is zero. Call it twice: once with valid inputs and once with b=0. Handle both cases at the call site with if err != nil. Then write a function that wraps this error with fmt.Errorf('divide failed: %w', err). Unwrap it with errors.Is.

Follow-up 1Write a custom error type: a struct that implements the error interface with an Error() string method. Include extra context fields. Use errors.As to extract the custom type at the call site.

Follow-up 2Write a function chain where each function can fail. Chain them so that any failure in the chain propagates up with wrapped context at each level. Trace the full error message at the top.

Still stuck?

Go blog — 'Error handling and Go'. Tour of Go — 'Errors'.

Milestone 04 · exact map

Goroutines — lightweight concurrency

Source milestone

Goroutines — what they are, how they differ from threads, the cost model

Primary exercise

Launch 5 goroutines that each sleep for a random duration and then print their index. Run the program and observe the non-deterministic print order. Add a sync.WaitGroup to wait for all of them to finish before the program exits. Without the WaitGroup, observe the program exiting before all goroutines complete.

Follow-up 1Launch 100 goroutines that each make a simulated network call (time.Sleep). Measure the wall time. Then do the same work sequentially. Write down the speedup.

Follow-up 2Introduce a goroutine leak: a goroutine that blocks forever on a channel receive that never gets sent to. Use runtime.NumGoroutine() to confirm the leak. Fix it.

Still stuck?

Tour of Go — 'Goroutines'. Go blog — 'Concurrency is not parallelism'.

Milestone 05 · exact map

Channels — communication between goroutines

Source milestone

Channels — how goroutines communicate, buffered vs unbuffered, select statement

Primary exercise

Write a producer goroutine that sends 10 integers to a channel, then closes it. Write a consumer that receives from the channel using range until it's closed. Run both. Then rewrite using a buffered channel of size 5 — observe that the producer can send 5 items without blocking before the consumer starts.

Follow-up 1Write a fan-out: one producer sends to N worker goroutines via N separate channels. Each worker processes and sends results to a single results channel. Collect all results in main.

Follow-up 2Use a select statement with two channels and a time.After timeout. If neither channel sends within 1 second, print 'timeout'. Test both the timeout path and the success path.

Still stuck?

Tour of Go — 'Channels' and 'Select'. Go blog — 'Go Concurrency Patterns'.

Milestone 06 · exact map

net/http — handlers and routing

Source milestone

The standard library net/http — writing an HTTP handler, registering routes, serving responses

Primary exercise

Write an HTTP server with three routes: GET /health returns 200 OK, GET /users returns a JSON array of hardcoded users, POST /users reads a JSON body and prints it. Use only the standard library. Test with curl. Write a comment on what http.Handler is and how http.HandleFunc satisfies it.

Follow-up 1Write a custom http.Handler as a struct with a ServeHTTP method. Give it a dependency (a logger or a counter) that's injected through the struct. Register it with http.Handle.

Follow-up 2Add path parameter parsing without a router library: parse /users/123 and extract '123' by splitting the URL path string. Return user data by ID.

Still stuck?

Go docs — net/http package. Go blog — 'Writing Web Applications'.

Milestone 07 · exact map

JSON encoding and decoding

Source milestone

JSON encoding and decoding — struct tags, marshaling to and from JSON, handling optional fields

Primary exercise

Define a User struct with json struct tags. Marshal a User to JSON and print it. Then unmarshal a JSON string into a User and access its fields. Add an optional field using a pointer type (*string) and a json:",omitempty" tag — confirm it's omitted from the output when nil but included when set.

Follow-up 1Write a custom JSON marshaler for a type that doesn't have a natural JSON representation — for example, a time.Time that should serialize as a Unix timestamp integer.

Follow-up 2Decode a JSON response from an HTTP request into a typed struct. Handle the case where the response body is malformed JSON — return a descriptive error.

Still stuck?

Go docs — encoding/json package. Go blog — 'JSON and Go'.

Milestone 08 · exact map

Database connection — sql.DB and queries

Source milestone

Connecting to a database — sql.DB, prepared statements, scanning rows into structs

Primary exercise

Connect to a SQLite database using database/sql and the mattn/go-sqlite3 driver. Create a users table. Write functions to insert a user, query all users, and query a user by ID. Use prepared statements for the insert and ID lookup. Scan rows into User structs. Handle the case where no row is found (sql.ErrNoRows).

Follow-up 1Wrap the insert and a related operation in a transaction. Test what happens when the second operation fails — confirm the first operation is rolled back.

Follow-up 2Replace the raw sql queries with named parameters and measure whether it changes behavior. Add an index on the email column and write a query that uses it.

Still stuck?

Go docs — database/sql package. Go wiki — 'SQLDrivers'.

Milestone 09 · exact map

Middleware — wrapping handlers

Source milestone

Middleware — wrapping handlers for logging, auth, CORS

Primary exercise

Write a logging middleware that wraps any http.Handler: it records the method, path, and duration of every request. Write a CORS middleware that adds the appropriate headers to every response. Chain both middlewares around your user endpoints using a simple wrapper function pattern.

Follow-up 1Write an auth middleware that checks for an Authorization header. Return 401 if it's missing, call the next handler if it's present. Apply it only to protected routes.

Follow-up 2Write a rate-limiting middleware using a sync.Map of IP addresses and request counts. Return 429 if a client exceeds 10 requests per minute.

Still stuck?

Go blog — 'Making a RESTful JSON API in Go'. Search 'Go middleware pattern'.

Milestone 10 · exact map

Go modules — dependency management

Source milestone

Go modules — go.mod, importing packages, versioning

Primary exercise

Initialize a new module with go mod init. Add one external dependency (a router like chi or a logger like slog). Run go mod tidy. Inspect go.mod and go.sum — write a comment explaining what each file's job is. Then vendor the dependencies with go mod vendor and confirm the project builds with -mod=vendor.

Follow-up 1Pin a dependency to a specific version in go.mod. Then upgrade it to the latest with go get package@latest. Observe what changes in go.sum.

Follow-up 2Write a replace directive in go.mod that substitutes an external package with a local copy. Build the project and confirm it uses your local version.

Still stuck?

Go docs — 'Using Go Modules'. go.dev/blog/using-go-modules.

Uptime Checker · 7 milestones

Hono / Hono JSX

Framework surface: routing, context, SSR JSX, middleware, bindings, and errors

Milestone 01 · exact map

Routing basics — handlers, params, and route groups

Source milestone

Routing basics — app.get/post/etc, path params, route grouping

Primary exercise

Build a small Hono app with a grouped /api route. Add GET /api/services, GET /api/services/:id, and POST /api/services. Parse the path parameter, return 404 for an unknown ID, and verify every route with curl.

Follow-up 1Add a nested /api/services/:id/checks route and confirm the parameter is available inside the grouped handler.

Follow-up 2Send GET, POST, and DELETE requests to the same path and document which handler runs for each method.

Still stuck?

Hono docs — Routing and Route Grouping.

Milestone 02 · exact map

Context object — request and response helpers

Source milestone

Context object — c.req, c.res, c.json(), c.html(), what's attached to it per-request

Primary exercise

Write one handler that reads a query parameter, a request header, and a JSON body through c.req, then returns the normalized result with c.json(). Add another handler that returns an HTML diagnostic page with c.html().

Follow-up 1Set a custom response header through the context and verify it with curl -i.

Follow-up 2Store a request-scoped value with c.set(), read it later in the handler, and confirm a second request does not inherit it.

Still stuck?

Hono docs — Context and Request.

Milestone 03 · exact map

Hono JSX — server-rendered HTML

Source milestone

Hono JSX — server-rendered by default, how a component returns HTML not a virtual DOM tree to hydrate

Primary exercise

Create a StatusPage JSX component that receives typed service data and renders semantic HTML. Open it in the browser, inspect View Source, and confirm the complete service list arrived as HTML without a client bundle.

Follow-up 1Disable JavaScript and confirm the status page still renders fully.

Follow-up 2Extract a reusable ServiceStatus component and pass typed props for name, state, latency, and last checked time.

Still stuck?

Hono docs — JSX and JSX Renderer.

Milestone 04 · exact map

Client components — explicit interactivity

Source milestone

Client components — the explicit opt-in mechanism, and when you actually need one vs. plain SSR

Primary exercise

Add one genuinely interactive control to the status page, such as a client-side incident filter or refresh button. Keep the service list server-rendered. Document why only that control needs client JavaScript.

Follow-up 1Remove the client script and confirm the static page remains usable while only the enhancement disappears.

Follow-up 2Replace the interactive control with a plain HTML form submission and compare the complexity and user experience.

Still stuck?

Hono docs — Client Components; progressive enhancement references.

Milestone 05 · exact map

Middleware — composition and next()

Source milestone

Middleware — what it is, built-in middleware (logger, cors), writing a small custom one

Primary exercise

Add Hono logger and CORS middleware, then write custom timing middleware that records method, path, status, and elapsed milliseconds. Use await next() correctly so the timer includes the downstream handler.

Follow-up 1Write middleware that rejects requests missing an X-Operator-Key header and prove the route handler never runs.

Follow-up 2Swap middleware order and observe how the logs or headers change. Explain why ordering is part of behavior.

Still stuck?

Hono docs — Middleware and built-in middleware.

Milestone 06 · exact map

Environment bindings — typed platform access

Source milestone

Environment bindings — how env.DB, env.KV, etc. get typed and passed into a handler

Primary exercise

Define a Bindings type containing DB and STATUS_KV. Create a route that reads both bindings through c.env and returns a small diagnostic response. Intentionally misspell one binding and let TypeScript expose the mismatch.

Follow-up 1Add a separate development binding name and use a typed environment configuration to select it.

Follow-up 2Move binding access behind a small repository function so route code no longer knows the binding API directly.

Still stuck?

Hono docs — Cloudflare Workers adapter and Bindings typing.

Milestone 07 · exact map

Error handling — controlled failure responses

Source milestone

Error handling — app.onError, throwing HTTPException, what an unhandled error does on Workers

Primary exercise

Configure app.onError to return a stable JSON error shape. Add one route that throws HTTPException(404) and another that throws an ordinary Error. Verify status codes, response bodies, and that internal details are not leaked.

Follow-up 1Add app.notFound and confirm unknown routes use a different response from internal failures.

Follow-up 2Throw from inside middleware and verify the same global error policy handles it.

Still stuck?

Hono docs — Error Handling and HTTPException.

Uptime Checker · 7 milestones

Cloudflare Workers

Runtime model, scheduled work, limits, environments, and deployment

Milestone 01 · exact map

Workers execution model — no durable module state

Source milestone

The Workers execution model — what's isolated per-request, what isn't, why you can't just hold state in a module-level variable and expect it to persist reliably

Primary exercise

Create a module-level counter and increment it in a fetch handler. Send repeated requests locally and after deploy, then document why any apparent persistence is an optimization rather than a storage guarantee. Replace it with a durable D1 or KV-backed value.

Follow-up 1Run concurrent requests and observe whether the counter produces a reliable sequence.

Follow-up 2Restart local development and confirm module state disappears while persisted state remains.

Still stuck?

Cloudflare Workers docs — Runtime APIs and How Workers works.

Milestone 02 · exact map

waitUntil — post-response work

Source milestone

waitUntil and the execution context — doing work after the response is sent without the worker being killed early

Primary exercise

Build a route that immediately returns 202 and schedules a simulated audit-log write with c.executionCtx.waitUntil(). Verify the response arrives before the background work finishes and that the write completes.

Follow-up 1Remove waitUntil and compare whether the background operation reliably completes.

Follow-up 2Make the background promise reject and add explicit logging so the failure is observable without affecting the response already sent.

Still stuck?

Cloudflare Workers docs — ExecutionContext.waitUntil().

Milestone 03 · exact map

Scheduled events — cron-driven polling

Source milestone

Scheduled events — the scheduled() export, how cron syntax maps to trigger frequency in wrangler config

Primary exercise

Add a scheduled handler and a cron trigger in wrangler configuration. In local development, trigger it manually and have it poll one known endpoint, logging normalized status, latency, and timestamp.

Follow-up 1Configure a second cron expression and confirm which trigger value reaches the handler.

Follow-up 2Extract the poll-cycle function so both a debug HTTP route and scheduled() can call the same testable logic.

Still stuck?

Cloudflare Workers docs — Cron Triggers and local testing.

Milestone 04 · exact map

CPU time limits — synchronous work budget

Source milestone

CPU time limits — what counts against it, why an infinite loop or heavy synchronous work is dangerous here specifically

Primary exercise

Write a benchmark route that performs increasing amounts of synchronous computation and record CPU time in local/preview logs. Refactor the task into smaller or more appropriate work and document what waiting on fetch does versus CPU computation.

Follow-up 1Add an accidental large JSON transformation and measure its effect before and after simplifying it.

Follow-up 2Introduce a bounded loop guard and prove it prevents malformed input from causing runaway CPU work.

Still stuck?

Cloudflare Workers docs — Limits and CPU time.

Milestone 05 · exact map

Subrequest limits — bounded fan-out

Source milestone

Subrequest limits — how many outbound fetches a single invocation can make, and why that caps your fan-out design directly

Primary exercise

Implement a poller that fans out to a configurable list of mock services. Count outbound fetches explicitly and reject or batch a configuration that would exceed your chosen per-invocation budget.

Follow-up 1Run five checks in parallel and compare duration with a sequential implementation.

Follow-up 2Split a larger service list into batches and document the tradeoff between one invocation, queues, and multiple scheduled jobs.

Still stuck?

Cloudflare Workers docs — Subrequest limits.

Milestone 06 · exact map

Cold starts — startup cost awareness

Source milestone

Cold starts — what makes Workers fast to cold-start relative to a traditional server, and what still costs time

Primary exercise

Measure the first and subsequent request latency for a lightweight Worker route. Then add expensive module-scope initialization and measure again. Move avoidable work out of startup and compare.

Follow-up 1Import a large dependency temporarily and inspect bundle size and startup behavior.

Follow-up 2Cache an immutable parsed configuration at module scope and explain why this optimization is safe even though mutable state is not durable.

Still stuck?

Cloudflare Workers docs — performance and startup guidance.

Milestone 07 · exact map

Wrangler environments, secrets, and deployment

Source milestone

wrangler dev vs wrangler deploy — local dev loop, environments, secrets

Primary exercise

Create development and production Wrangler environments with separate D1/KV bindings. Add a secret locally and in the deployed environment, then write a diagnostic route that confirms presence without exposing the value.

Follow-up 1Deploy to a preview environment and verify it cannot read production data.

Follow-up 2Delete a required binding from one environment and confirm startup or type validation catches the configuration error.

Still stuck?

Cloudflare Workers docs — Wrangler environments, bindings, and secrets.

Uptime Checker · 6 milestones

Cloudflare D1

Relational ownership of services, history, incidents, and queries

Milestone 01 · exact map

Schema design — services, history, incidents

Source milestone

Schema design for this project — services, incidents, status_history tables and their relationships

Primary exercise

Design and create services, status_history, and incidents tables with primary keys, foreign keys, timestamps, and indexes that support the status-page queries. Draw the relationships before writing SQL.

Follow-up 1Insert an incident for a nonexistent service and decide whether foreign-key enforcement matches your intended policy.

Follow-up 2Explain which table owns current configuration, which records immutable observations, and which records a state transition episode.

Still stuck?

Cloudflare D1 docs — SQL API; SQLite foreign keys and indexes.

Milestone 02 · exact map

Migrations — reproducible schema evolution

Source milestone

Migrations — wrangler d1 migrations, keeping schema changes versioned and repeatable

Primary exercise

Create an initial migration, apply it locally, seed data, then add a second migration that introduces an enabled flag or latency column. Rebuild a fresh local database using only migrations and verify the schema matches.

Follow-up 1Attempt to apply migrations twice and document how Wrangler tracks applied versions.

Follow-up 2Write a reversible data-preserving migration plan for renaming a column in SQLite.

Still stuck?

Cloudflare D1 docs — Migrations.

Milestone 03 · exact map

D1 binding API — prepare, bind, run, all, first

Source milestone

The D1 binding API — prepare(), bind(), .run(), .all(), .first(), and when to use each

Primary exercise

Implement repository functions for createService, findServiceById, listServices, and updateServiceState. Use prepare/bind and deliberately choose run, first, or all according to the expected result.

Follow-up 1Pass a quote-containing service name and confirm bound parameters avoid SQL injection and escaping bugs.

Follow-up 2Call first() for a missing row and define a clear repository-level not-found result.

Still stuck?

Cloudflare D1 docs — Prepared statements and return methods.

Milestone 04 · exact map

Batch operations — one poll cycle

Source milestone

Batch operations — D1's batch() for multiple statements, and why it matters for write-heavy operations like recording a poll cycle

Primary exercise

Record one poll cycle containing several status_history inserts through DB.batch(). Compare the implementation and timing with sequential awaits, and decide what should happen if one statement fails.

Follow-up 1Add an update to the service current-state metadata in the same batch and verify all expected rows are written.

Follow-up 2Inject one invalid statement and inspect the failure behavior before choosing your recovery policy.

Still stuck?

Cloudflare D1 docs — batch statements.

Milestone 05 · exact map

Domain queries — current status and incidents

Source milestone

Query patterns for this domain — get current status per service, get incident history for a service, get all incidents in a date range

Primary exercise

Write and verify three queries: latest status per service, incident history for one service, and incidents overlapping a date range. Seed edge-case data so ties and services with no history are handled deliberately.

Follow-up 1Add indexes and inspect EXPLAIN QUERY PLAN before and after.

Follow-up 2Query the most recently degraded services and confirm ordering uses observation time rather than service creation time.

Still stuck?

D1/SQLite docs — window functions, joins, and query plans.

Milestone 06 · exact map

Consistency, transactions, and retention

Source milestone

D1's consistency and transaction model — what you can and can't rely on relative to a traditional RDBMS

Primary exercise

Write a short decision note defining which uptime-checker operations require atomicity, what D1 guarantees you rely on, and how the application handles duplicate scheduled invocations or partial failures. Implement an idempotency key for a poll cycle.

Follow-up 1Run the same poll-cycle write twice and verify duplicates are prevented or safely tolerated.

Follow-up 2Create and test a retention query that deletes or aggregates old status_history while preserving incident history.

Still stuck?

Cloudflare D1 docs — transactions, consistency, and limits.

Uptime Checker · 5 milestones

Workers KV

Fast current-status snapshots with explicit staleness behavior

Milestone 01 · exact map

KV binding API — snapshot CRUD

Source milestone

The KV binding API — get(), put(), delete(), list(), and JSON serialization patterns

Primary exercise

Write a complete current-status snapshot to one KV key as JSON, read it back with type validation, list versioned snapshot keys, and delete a test key. Keep serialization in one adapter rather than spreading JSON.parse/stringify across routes.

Follow-up 1Write malformed JSON manually and confirm the adapter returns a controlled error.

Follow-up 2Store metadata alongside the value and verify it can be read without changing the snapshot payload contract.

Still stuck?

Workers KV docs — get, put, list, delete, and metadata.

Milestone 02 · exact map

Eventual consistency — acceptable stale reads

Source milestone

Eventual consistency — what it means concretely for a value written by a cron job and read by a status page

Primary exercise

Add generatedAt and pollCycleId fields to the snapshot. After a write, have the status route report the age and cycle ID it observed. Document why a briefly stale read is acceptable here and where it would not be.

Follow-up 1Simulate reading an older snapshot and ensure the page labels it as stale rather than claiming it is current.

Follow-up 2Compare the snapshot model with an operation that would require immediate read-after-write consistency and explain why KV would be a poor fit there.

Still stuck?

Workers KV docs — consistency model.

Milestone 03 · exact map

TTL and expiration — stale-data policy

Source milestone

TTLs and expiration — whether the status snapshot should expire, and what happens on read if it does

Primary exercise

Choose and implement a snapshot expiration policy. When the key is missing or expired, return a clear no-current-data state or fall back to a D1 latest-status query. Test both paths.

Follow-up 1Set an intentionally short TTL locally and verify expiration behavior.

Follow-up 2Separate “key missing” from “snapshot present but stale” in the response model and UI.

Still stuck?

Workers KV docs — expiration and TTL.

Milestone 04 · exact map

KV versus D1 — explicit ownership boundary

Source milestone

KV vs D1 for this exact project — articulating the boundary in your own words, not just reciting the docs

Primary exercise

Write a one-page storage decision table for services, status_history, incidents, and current snapshot. Then implement a route that proves the boundary: configuration/history comes from D1; the public current view comes from KV with a D1 fallback.

Follow-up 1Move incident history into KV temporarily and list the query/update problems that appear.

Follow-up 2Move the current snapshot to a full D1 query and measure or reason about the additional work on every page load.

Still stuck?

Cloudflare storage docs — choosing D1 versus KV.

Milestone 05 · exact map

Read/write shape — one snapshot per cycle

Source milestone

Read/write limit shape — why KV is built for high-read/low-write and how that matches (or doesn't) each piece of this project's data

Primary exercise

Instrument snapshot reads and writes. Verify one poll cycle performs one KV write while many status-page requests perform reads. Add a guard preventing a write per individual service check.

Follow-up 1Generate 100 simulated page reads and confirm they do not mutate KV.

Follow-up 2Estimate the daily read/write count for your expected traffic and record it in the project README.

Still stuck?

Workers KV docs — limits and pricing model.

Uptime Checker · 5 milestones

Vitest for Workers

Runtime-faithful tests for bindings, scheduled handlers, and failure paths

Milestone 01 · exact map

vitest-pool-workers — workerd test runtime

Source milestone

vitest-pool-workers setup — the config that runs your tests inside workerd, not a Node shim

Primary exercise

Configure @cloudflare/vitest-pool-workers and write a smoke test against the Hono app. Prove the test is running in the Workers runtime by checking a Workers API and confirming an unavailable Node-only assumption fails.

Follow-up 1Run the same test under an ordinary Node Vitest config and document the behavioral difference.

Follow-up 2Add the test command to CI and ensure it starts from a clean environment.

Still stuck?

Cloudflare Workers docs — Vitest integration.

Milestone 02 · exact map

D1 test isolation — seeded relational state

Source milestone

Mocking or seeding D1 in tests — using a test binding, resetting state between tests

Primary exercise

Create a helper that applies migrations and seeds service/history rows for each test. Write two tests whose data would conflict if isolation were broken, and verify each starts with the expected clean state.

Follow-up 1Test a foreign-key or unique-constraint failure and assert the repository returns the intended domain error.

Follow-up 2Create a fixture builder for a service with a configurable sequence of healthy and failed checks.

Still stuck?

Workers Vitest D1 documentation and test isolation guidance.

Milestone 03 · exact map

KV test isolation — deterministic snapshots

Source milestone

Mocking or seeding KV in tests — same idea, isolated per test

Primary exercise

Seed a current-status snapshot in the test KV binding, read it through the real adapter, then delete or replace it. Write a second test proving the previous snapshot does not leak into its state.

Follow-up 1Seed malformed JSON and assert the route returns the controlled fallback response.

Follow-up 2Use a fake generatedAt timestamp to test fresh, stale, and expired states deterministically.

Still stuck?

Workers Vitest KV documentation.

Milestone 04 · exact map

Scheduled handler tests — assert side effects

Source milestone

Calling scheduled() directly in a test — constructing a fake ScheduledEvent and asserting on side effects

Primary exercise

Invoke the exported scheduled handler in a test with seeded D1 services and mocked outbound fetches. Await the execution context, then assert history rows, incident transitions, and the KV snapshot.

Follow-up 1Run the handler twice with the same poll-cycle identity and verify idempotent behavior.

Follow-up 2Assert that the snapshot is written once after all service results are processed, not once per service.

Still stuck?

Cloudflare Vitest docs — scheduled events and execution contexts.

Milestone 05 · exact map

Failure-path tests — partial success and resilience

Source milestone

Testing failure paths — a service that times out, a D1 write that fails, a KV read that returns null

Primary exercise

Write separate tests for a timed-out service, a rejected fetch, a missing KV snapshot, and a simulated storage failure. Verify one failing service does not prevent other results from being recorded and surfaced.

Follow-up 1Use fake timers or an abort signal to make timeout tests fast and deterministic.

Follow-up 2Assert logs/error responses contain actionable context without leaking secrets.

Still stuck?

Vitest docs — mocking, fake timers, and Workers testing guidance.