Tutorial: Build Hero HQ
You've just been hired as the backend engineer for Hero HQ, a staffing agency that dispatches superheroes to city-scale emergencies. The heroes are powerful but allergic to paperwork. Your job: build the API that keeps the cape-wearing chaos organized — and learn Lauren, end to end, while you do it.
This is the guided, build-one-app path through Lauren. Where the
Quickstart is a five-minute sprint to see the shape of
a Lauren app, the tutorial is the afternoon project: you start from pip install and end
with a validated, dependency-injected, guarded, session-aware, real-time, tested API,
adding exactly one concept per step.
Tip: ⚡ How to follow along
Type the code, don't just read it — heroism is a contact sport. Each step ends with a ✅ Checkpoint showing the app's state, so if something drifts you can diff against it. The finished app lives in
docs/tutorial/hero_hq/and is covered by the test suite, so every snippet here is real, running code.
What you'll build
A backend for dispatching heroes: recruit them, validate their (frankly improbable) paperwork, store them on a shared roster, organize them into teams, keep villains out, remember who's logged in, stream live mission updates, and ship the whole thing to production without the pager going off.
Meet the cast
Lauren's concepts are easier to remember when they have a face. You'll work with:
| Character | Who they are | What they teach |
|---|---|---|
| Captain Singleton | There is exactly one of him, ever. Runs the HQ power grid. | Scope.SINGLETON |
| The Sidekick | A fresh one shows up per mission and goes home after. | Scope.REQUEST |
| The Auditor | Rejects malformed hero paperwork with a withering 422. | Validation / extractors |
| The Door Bouncer | Checks badges. Bounces villains. | Guards / auth |
| The Villain | Exists mainly to trip your error envelopes. | HTTPError subclasses |
| Mission Control | The live-ops desk that never sleeps. | SSE / WebSockets / tasks |
The steps
Install Lauren, write one controller, and serve your first route. Hello, hero.
Typed request bodies and path params, automatic validation, and the Auditor's 422s.
Dependency injection and scopes — Captain Singleton's shared roster vs. the Sidekick.
Guards and custom errors — keep villains off the roster with a badge check.
Real-time: an SSE status feed, fire-and-forget dispatch tasks, and WebSocket comms.
Test the whole agency in-process with TestClient and WsTestClient — including the rejections.
Success: 🎓 The full journey
All nine steps are here — from
pip installto a deployed, tested, real-time API. Follow them in order, or jump to the one you need.
Prerequisites: Python 3.11+, a terminal, and the willingness to name variables after superheroes. No prior Lauren knowledge required.
Ready? Recruit your first hero →