Backend Architecture

Everything in backend/app/ follows one flow: a model defines the shape of data, CRUD functions do the actual database work, routes expose that over HTTP, and deps wires shared plumbing (like “who’s logged in?”) into those routes. Once you know that chain, the whole backend is just repetitions of it.

Entry & wiring

File	What it’s for
app/main.py	Creates the FastAPI app, sets up CORS, mounts everything else
app/core/config.py	All settings — read from .env (SECRET_KEY, POSTGRES_*, etc.)
app/core/db.py	Database engine and session setup
app/core/security.py	Password hashing and JWT creation/verification

API layer (app/api/)

File	What it’s for
routes/login.py	Auth — login, password recovery
routes/users.py	User CRUD and “me” endpoints
routes/items.py	The example resource — copy this pattern for your own
routes/private.py	Superuser-only endpoints
routes/utils.py	Health check, test-email
deps.py	Shared dependencies — get_current_user, DB session injection
main.py (in api/)	Stitches all routers together under /api/v1

Data layer

File	What it’s for
app/models.py	Every SQLModel class — DB tables plus their Create/Update/Public shapes
app/crud.py	The actual database operations the routes call into
app/alembic/versions/	One file per schema change, in order

Startup

File	What it’s for
app/backend_pre_start.py	Waits for the database to be reachable before the app starts
app/initial_data.py	Creates the first superuser on first run

The pattern to remember

New feature = a new class in models.py → new functions in crud.py → a new route file under api/routes/ → wired into api/main.py. Almost everything you build follows that exact order.