Using This Template

This handbook exists to teach you how to build real, working software — using AI as a serious tool, not as a magic box you feed prompts into and hope. Everything here is built on top of one starting point: the official FastAPI full-stack template, with Spec Kit, Serena, and a devcontainer already wired in — that’s cmx-learn/fastapi-template, the repo you’ll actually create your project from. This page explains what that actually means before you write a line of code.

What’s in the box

The template isn’t a toy scaffold — it’s the FastAPI team’s own production reference stack:

• Backend: FastAPI + SQLModel (the ORM) + PostgreSQL, with JWT authentication, email-based password recovery, and Alembic managing database migrations.
• Frontend: React + TypeScript, built with Vite, using TanStack Query and TanStack Router, styled with Tailwind and shadcn/ui.
• Infrastructure: Docker Compose ties it together locally; Traefik handles routing and HTTPS in deployment; GitHub Actions runs CI.

That’s a lot of names. You don’t need to understand all of them today — you need to know they’re there, and that each one is a real, independent thing an AI assistant might reach for without asking.

Why this template, and why it won’t hold your hand

Worth saying plainly: this template was not designed to be beginner-friendly. It was designed to be correct — the kind of base an experienced team would start a real product on. That’s exactly why we’re using it: you’re learning to build the way it’s actually done, not a simplified version you’ll have to unlearn later.

The tradeoff is that nothing here explains itself. If you ask an AI assistant to “add a feature” without understanding what’s already here, it will happily generate code across five different concerns at once — and you’ll have working code you can’t explain. That’s the failure mode this whole handbook is built to prevent.

What you already know vs. what’s genuinely new

You know Python fundamentals — functions, classes, type hints. That covers more of this stack than you’d expect:

Already covers it	Genuinely new ground
Writing FastAPI route handlers (they’re just Python functions with decorators)	SQL and migrations — thinking in relations, foreign keys, and why an auto-generated migration can be silently wrong
Defining SQLModel/Pydantic models (they’re just typed Python classes)	Auth — tokens vs. sessions, password hashing, why a “secret key” left at its default is a real vulnerability, not a lint warning
Basic control flow, error handling, testing logic	React and TypeScript — a component model and a type system that share nothing with Python’s
	Docker — why a container failing has nothing to do with whether your code is correct

When you’re working in the left column, trust your instincts and move fast. When you’re working in the right column, slow down — that’s where you’re actually learning something new, and it’s where AI-generated code deserves the most scrutiny, not the least.

How we use AI here

The point of this handbook isn’t to avoid AI — it’s to use it in a way that makes you better at this, not just faster at shipping code you don’t understand. A few ground rules, all the way through:

Explain it back

Before you accept a chunk of AI-generated code, explain in your own words what it does and why. If you can’t, that’s a signal to ask the AI to walk you through it — not to accept and move on. This one habit is the single biggest factor in whether AI-assisted building actually teaches you anything.

• Work in small increments. Ask for one feature, one endpoint, one component at a time — not “build me the whole thing.” Small changes are ones you can actually review.
• Start with the AI on a leash. Use restrictive permission modes to start (ask-before-edit, not full-autonomy/“YOLO” modes) until you’ve built the judgment to know what a risky action looks like.
• Read the diff like it’s a coworker’s pull request. Because that’s what it is — a collaborator’s proposed change, not a finished decision.

None of this slows you down as much as it feels like it should. It’s the difference between building three features you understand and ten you’d have to hand back to an AI to explain to you later.

What’s next

The next pages walk through getting your environment running and building your first real feature end to end. If you haven’t set up your project yet, start there.