Makai is a connected backend failure journey inspired by the shape of Legend of Makai: keys, doors, shop upgrades, hostile stages, time pressure, and a final rescue. The fantasy layer is not decoration. It gives every system-design concept a promise to protect.

Ava, Beau, and Cleo enter Makai through the Gatehouse. At first, the promise is simple: coin pouches should not lose money. Then the promise grows sharper: one gate slot should have one rightful holder, shop retries should not double-charge, dispatch messages should not lie about uncommitted state, hot maps should survive viral load, mirror realms should expose consistency trade-offs, and final-tower decisions should not commit without a majority.

The goal is not to memorize patterns. The goal is to debug a concrete betrayal of player trust, state the invariant, choose a mechanism, point to evidence, and explain what the mechanism still does not solve.

These labs are reading-first, but they should feel like real software engineering. Senior system work often starts with unfamiliar code, a failing behavior, and a business promise that must be restored. The practice here is to read the test, inspect the implementation, learn the system-design concept just in time, write the fix, verify it, explain it, and commit it cleanly.

main is the green reference implementation and source of truth. Mission branches are intentionally broken starter branches for hands-on repair. When a mission branch exists, switch to it, expect the relevant tests to fail, fix the implementation, write a short report, and commit your work.

Use mission labs in this loop:

1. Read the mission ticket and the failing test.
2. Run the failing test on the mission branch.
3. Inspect the real implementation and schema that own the state transition.
4. Explore the concept enough to explain the fix.
5. Patch the implementation.
6. Run the targeted tests, then the broader level tests.
7. Write REPORT.md with the incident, evidence, mechanism, verification, and remaining risk.
8. Commit the fix with a message that names the mechanism.

Every exercise has a mission branch. main remains useful for comparison after you finish, but the primary practice loop starts on the mission branch.

Use GLOSSARY.md first for the project-local meaning, then search the topic names when you want deeper background. The goal is not to become encyclopedic before starting; it is to know which idea you are looking at while reading the code.

uv run python -m pytest

The public CLI stays sdl-db. It manages the six Makai schemas and resets old local schemas from the previous structure.

createdb system_design_labs || true
uv run sdl-db reset
uv run sdl-db migrate
uv run sdl-db seed
uv run sdl-db workload --iterations 50
uv run sdl-db status

The seed data creates one coherent Makai quest dataset: adventurers, coin pouches, a gate run, passage slots, reservations, shop idempotency records, dispatch messages, cache rows, shard rows, mirror-realm events, conflict notes, and final-tower drills. Treat those rows as evidence from the realm, not as fixtures to trust blindly.

A level is done when you can:

• Reproduce the failure, unsafe path, or pressure case with tests or the Postgres workload.
• Name the promise Makai made to the player or operator.
• Name the Makai state that changed: coin pouch, gate slot, key, shop checkout, dispatch, cache ward, shard route, mirror replica, or final-tower drill.
• State the invariant in one sentence.
• Point to evidence from a test, debugger session, SQL query, or workload row count.
• Draw the smallest useful diagram of the state transition, data flow, or failure window.
• Explain the mechanism that fixes, prevents, or contains the issue.
• Explain what the mechanism does not solve.
• For mission branches, commit the fix with a short REPORT.md.

Future labs should be planned here before code exists.