DEV Community: Azhar Alvi

Phase 8 — Making It Trustworthy: Hardening a FastAPI App with an Audit, a Test Net, and a Logging Bug I Typed Twice

Azhar Alvi — Sun, 16 Aug 2026 13:58:28 +0000

Phase 7 gave the app a brain. Phase 8 was about making it trustworthy — the unglamorous gate between "works on my machine" and "safe to put a URL in front of."

No new features. Instead: a security audit that probed my own API for leaks, a global exception handler so unexpected errors stop leaking internals, a five-test pytest suite that turns every manual check into a permanent one, and a git-history secrets sweep. Plus the war story — a logging placeholder I fat-fingered the same way twice, a test that silently never ran, and a login that failed because of one capital letter.

Spoiler: the app had zero leaks. Almost every bug this phase was in the terminal, not the code.

Index

Where we left off
The plan: prove it, then protect it
Step 1 — The warm-up: a /health endpoint
Step 2 — The audit: probe my own API for leaks
Step 3 — The safety net: a global exception handler
Step 4 — The test net: turning manual proofs into permanent ones
Step 5 — The isolation test: an in-memory database that lies convincingly
Step 6 — Pagination: putting a ceiling on an unbounded list
Step 7 — The secrets sweep: is anything sensitive in my git history?
The war story: the tool does what you type, not what you mean
Thinking like an attacker
Learning shortcut vs. production
Key habits to keep
Next up: Phase 9

Where we left off

Phase 7b ended with the seam holding: a category column, a rules engine, and a Gemini-backed LLMCategorizer living behind the same Categorizer contract — validated, cached, and with a fallback that was finally loud about failing.

I closed that post nagging at three things: the cache dies on restart, the model name is a drifting alias, and my free tier can't afford to be the default. All real. All enhancements.

But there was a bigger question I'd been walking past: is this thing actually safe to deploy? I had auth, I had owner-scoped queries, I believed users were isolated — but belief isn't proof. Phase 8 is where I stop believing and start verifying.

The plan: prove it, then protect it

The temptation was to jump straight to "add security stuff." I didn't. You can't harden what you haven't observed, so I ordered the work from lowest risk and highest evidence outward:

Step	What	Why this order
1	A `/health` endpoint	Purely additive warm-up; also the thing my host will ping in Phase 9
2	Audit the real API for leaks	Get evidence before writing a single fix — don't guess what leaks
3	Global exception handler	The one gap the audit couldn't test: the unexpected 500
4–5	A pytest suite	Turn every manual proof into a permanent, re-runnable one
6	Pagination	Put a ceiling on an unbounded list before it becomes a problem
7	Secrets / git-history sweep	The one item with real downside if skipped before going public

The principle from Phase 7 still drives it: observe first, then change one thing at a time. When something breaks, I want to know it broke in the thing I just touched.

Step 1 — The warm-up: a `/health` endpoint

Every real route in my app is auth-gated behind get_current_user. That's correct for expenses — but a monitoring system can't log in. So I need exactly one deliberately public, side-effect-free route that answers "are you alive?" with a fast, boring 200.

@app.get("/health")
def health_check():
    return {"status": "ok"}

Idea	Why it matters
No `Depends`, no auth	The absence is the point — a monitor hits it without a token
No DB call	It answers "is the process up," not "is every subsystem healthy." A deeper check is a conscious later step
Returns a plain `dict`	FastAPI serializes it to JSON automatically — no `response_model` needed for something this trivial

Additive, zero risk, and it's the exact URL Phase 9's host will hit to confirm the deploy is up before I even try to log in. Good warm-up.

Step 2 — The audit: probe my own API for leaks

This is the part I'd skipped in every previous project: actually attacking my own endpoints and recording what they return. Not "I think it 404s" — curl it and read the status line.

I grabbed a token once, stashed it in a shell variable, and fired four deliberately-bad requests. Here's the evidence table that came out:

#	Probe	Expected	Actual	Verdict
1	POST expense, negative amount	422	422	Input validation holds
2	GET `/expenses`, garbage token	401	401	Auth boundary holds
3	GET a non-existent expense id	404	404	Not-found path is clean
4	GET another user's expense id	404	404	Cross-user isolation holds

Two things I want to call out, because they're design wins, not luck:

Probe #1 dies at the schema, not the database. My ExpenseCreate declares amount with gt=0, so Pydantic rejects a negative amount before my route body ever runs. Nothing gets written. Validation at the edge means the dangerous code never executes.

Probe #4 returns 404, not 403 — on purpose. My query filters by both id and user_id == current_user.id, so a row I don't own comes back as None → 404. A 403 Forbidden would be the wrong choice here: it would confirm "this expense exists, you're just not allowed to see it," which leaks the record's existence. 404 says "nothing here for you" and reveals nothing.

The candid bit: the "raw stack trace" fear I'd been carrying is mostly unfounded on FastAPI. It doesn't put tracebacks in the HTTP response by default — it returns a generic 500 and logs the trace server-side. Tracebacks only leak into the body if you run with debug on. So the real production job isn't "hide the trace," it's "make sure debug stays off, and add a net for the unexpected." Which is Step 3.

Step 3 — The safety net: a global exception handler

The audit found zero leaks — but it also couldn't test one thing, because nothing in my app currently throws an unhandled error. Production code eventually will. When it does, I want a deliberate, consistent response — not whatever Starlette's default is.

FastAPI already handles two error families: my intentional HTTPExceptions (401/404/409) and validation errors (422). What it doesn't handle is the unexpected — a bug, a None where I assumed a value. A catch-all lets me log the full traceback server-side with a correlation id, and return a clean generic body to the client.

@app.exception_handler(Exception)
async def unhandled_exception_handler(request: Request, exc: Exception):
    error_id = uuid.uuid4().hex[:8]
    logger.exception(
        "Unhandled error [%s] on %s %s", error_id, request.method, request.url.path
    )
    return JSONResponse(
        status_code=500,
        content={"detail": "Internal server error", "error_id": error_id},
    )

Concept	What it does
`@app.exception_handler(Exception)`	Catches only what a more specific handler didn't — my `HTTPException`s and 422s keep their exact status codes
`logger.exception(...)`	Logs at ERROR level with the full traceback — the server-side record
`uuid4().hex[:8]`	A short correlation id, printed in both the log and the response
Generic `{"detail", "error_id"}` body	The client sees a reference code to quote to support — never internals

The critical nuance is that first row. A handler on the broad Exception type does not swallow my deliberate HTTPExceptions — if it did, every 404 would turn into a 500. So the design is a floor under the unexpected, not a replacement for my existing errors.

And I proved it — not by faith, by a throwaway /debug/boom route that raised on demand, watched the handler catch it, then deleted the route. The 404 regression check afterward confirmed the catch-all left my intentional errors alone. (Getting that log line to actually format is its own war story below.)

Step 4 — The test net: turning manual proofs into permanent ones

Everything I proved in Step 2 with curl — the 422, the 401, the 404, the isolation — evaporates the moment I change code. A test turns a one-time proof into a permanent guarantee, and it's the single most credible signal to a stranger reading the repo that the app actually works.

FastAPI's TestClient calls the app in-process — no uvicorn, no network, fast and isolated. I proved the harness with one trivial /health test first (prove the tooling before you trust the result), then added the real ones.

The interesting piece is testing authenticated paths without a live login, using dependency_overrides — and the trap that comes with it:

@pytest.fixture
def as_authenticated_user():
    def _fake_user():
        return User(id=1, name="Test User", email="test@example.com", hashed_password="x")
    app.dependency_overrides[get_current_user] = _fake_user
    yield
    app.dependency_overrides.clear()

Concept	What it does
`dependency_overrides`	Swaps a real dependency for a fake — auth is satisfied, the route runs
A fixture, not a global	The trap: a global override poisons every test, silently breaking the 401 test
`yield` split	Everything before is setup, everything after is teardown — the `.clear()` is what keeps tests isolated

The proof that the teardown works: after adding the fixture, my test_expenses_requires_auth test still returned 401. If the override had leaked, it would've gotten the fake user and failed. Isolation intact.

Step 5 — The isolation test: an in-memory database that lies convincingly

The highest-value test is the one thing I'd only proven by hand: cross-user isolation. But it writes to the database, so it can't touch my real expenses.db. That means a proper test-database fixture — and the trickiest concept of the whole phase.

@pytest.fixture
def test_db():
    engine = create_engine(
        "sqlite://",
        connect_args={"check_same_thread": False},
        poolclass=StaticPool,
    )
    Base.metadata.create_all(bind=engine)
    TestingSessionLocal = sessionmaker(bind=engine, autoflush=False, autocommit=False)

    def _override_get_db():
        db = TestingSessionLocal()
        try:
            yield db
        finally:
            db.close()

    app.dependency_overrides[get_db] = _override_get_db
    seed = TestingSessionLocal()
    try:
        yield seed
    finally:
        seed.close()
        app.dependency_overrides.clear()
        Base.metadata.drop_all(bind=engine)

The StaticPool line is the one to internalize. TestClient runs requests in a thread pool, and a normal in-memory SQLite database is per-connection — a second connection sees an empty database, so my seeded rows would vanish. poolclass=StaticPool forces SQLAlchemy to reuse one single connection for everything, so the schema and seeded data persist across request threads. Without it, this test fails in a baffling way.

The test itself seeds two users and one expense owned by user2, then makes the same request as each identity:

def test_cross_user_isolation(test_db):
    # ... seed user1, user2, and an expense owned by user2 ...

    app.dependency_overrides[get_current_user] = lambda: User(id=u2_id)
    owner = client.get(f"/expenses/{expense_id}")
    assert owner.status_code == 200      # the control

    app.dependency_overrides[get_current_user] = lambda: User(id=u1_id)
    other = client.get(f"/expenses/{expense_id}")
    assert other.status_code == 404      # the guarantee

The 200 assertion is the control, and it's what stops this from being a false pass. It proves the row genuinely exists and is readable — so the following 404 can only mean my owner-scoped query hid it from a different user. Same id, two identities, two outcomes. That's the isolation guarantee, now permanent.

(This test almost didn't run at all — see the war story.)

Step 6 — Pagination: putting a ceiling on an unbounded list

My list_expenses was returning every row for the user with no ceiling. Fine at 12 rows, a latent problem at 10,000. Two query params fix it — with validation at the edge:

@app.get("/expenses", response_model=List[ExpenseRead])
def list_expenses(
    db: Session = Depends(get_db),
    current_user: User = Depends(get_current_user),
    limit: int = Query(default=50, ge=1, le=100),
    offset: int = Query(default=0, ge=0),
):
    expenses = db.scalars(
        select(Expense)
        .where(Expense.user_id == current_user.id)
        .order_by(Expense.spent_on.desc(), Expense.id.desc())
        .limit(limit)
        .offset(offset)
    ).all()
    return expenses

The non-obvious part: offset/limit is meaningless without a deterministic ORDER BY. SQLite makes no promise about row order unless you ask, so "skip 20, take 20" could overlap or drop rows between requests if the order shifts. Pagination and ordering are a package deal — hence the order_by.

The actual hardening is le=100: a caller asking for limit=999 gets a clean 422 instead of defeating the whole point. And I named the behavior change out loud — the list now returns max 50 by default where it used to return everything — so future-me isn't surprised when the frontend eventually needs a "load more."

Step 7 — The secrets sweep: is anything sensitive in my git history?

The one mental model to never forget: git history is a security camera that never stops recording, and deleting a file does not delete its past. If a secret appeared in any commit — even one I later "undid" — it's still recoverable and will go public the moment I push.

So a secrets audit is really three questions, and people who get burned only ask the first:

Question	Command	What it proves
Tracked now?	`git ls-files \	grep -iE "env\
File ever committed?	{% raw %}`git log --all --oneline -- backend/.env`	Past tense, by filename
Value ever committed, any file?	`git log --all --oneline -S "actual-value"`	Past tense, by content

All three came back clean. But question 1 taught a bonus lesson: it matched backend/alembic/env.py — Alembic's migration script, which just has the letters "env" in its name. A total false positive. A filter matches strings, not meaning — so you always eyeball what matched instead of trusting the filter.

The through-line from question 3: a secret leaks by content, not filename. Someone hardcodes SECRET_KEY = "..." into a .py "just to test," commits it, then later moves it to .env. The .env history is spotless — but the value is in that old commit forever. Only the pickaxe (git log -S) searching for the actual value catches that.

(Honest note I wrote down: a clean pickaxe only proves the current values were never committed. If a secret has ever lived somewhere I'm unsure about, the bulletproof move before a public deploy is to rotate it anyway. Rotation beats archaeology.)

The war story: the tool does what you type, not what you mean

Phase 7b's theme was "everything that isn't your code lying to you." Phase 8's theme was quieter and more humbling: my own typing, and tools doing exactly what I typed instead of what I meant. Almost none of it was in the application code.

Gotcha 1 — the logging placeholder I fat-fingered twice

My shiny new exception handler ran, the client got its 500 — but the server log was garbage:

Message: 'Unhandled error [$s] on $s %s'
Arguments: ('a06f2a97', 'GET', '/debug/boom')

See the $s? I'd typed $s instead of %s. Python's logging uses %-style formatting, so the interpolation failed and it dumped the raw message + args block. I fixed the middle one, re-ran — and it still broke, because I'd missed the one inside the brackets: [$s]. On a US keyboard % is Shift+5 and $ is Shift+4, adjacent keys. I hit the wrong one, in the same line, twice.

The lesson isn't "type carefully." It's that the whole point of the handler — a readable server-side log — was silently defeated by one wrong character, and the only reason I caught it was reading the actual log output instead of assuming it worked. Same energy as Phase 7b's silent except.

Gotcha 2 — a test that never ran

I added test_cross_user_isolation, ran pytest, saw green, and almost celebrated. Then I read the first line:

collected 3 items

Three. I'd written a fourth. It wasn't failing — it didn't exist as far as pytest was concerned. The function had gotten indented so it was nested inside another, which makes it invisible to collection (pytest only finds top-level test_* functions). No error, no failure, just... absent.

Now collected N items is the first thing I read, before the pass/fail. A green suite that silently skips your most important test is worse than a red one.

Gotcha 3 — the login that failed on one capital letter

Coming back after a few days, my saved token was stale (JWTs expire; shell variables die with the terminal). Fine — re-authenticate. Except the login kept returning a KeyError: 'access_token'. I tried passwordd. Failed. I knew the password was Passwordd with a capital P — tried that. Still failed.

The fix, as always: stop guessing, strip the pipeline, read the raw response. The real problem was the email — I'd been typing frontend1@test.com when the account was Frontend1@test.com. Capital F.

The design lesson underneath: my login returns the same generic 401 for a bad email or a bad password — which is correct (never tell an attacker which field was wrong) — but it means the error can't tell you which one you fat-fingered. That's exactly why "read the raw response" beats "stare at the error message."

Gotcha 4 — the terminal's invisible passengers

One curl command died with:

bash: $'\302\226\302\226curl': command not found

\302\226 is the UTF-8 for an invisible control character. Two of them had ridden along when I pasted from a rich-text source, so bash tried to run a command literally named ‖‖curl. The command was perfect; the paste smuggled in garbage bytes. Same family as Phase 7b's hidden comma — you can't debug what you can't see, so cat -v (which prints control characters) and re-typing by hand are the escape hatches.

The through-line across all four: before I'd fixed a single line of application code this phase, my keyboard, my clipboard, my shell, and pytest's collector had each quietly done something other than what I intended. The bug is rarely where you first look — and it's often not even in your code.

Thinking like an attacker

Same habit as always — try to break it before reality does:

Attack	Defense
POST a negative amount	Pydantic `gt=0` → 422, dies at the schema, never touches the DB
Present a garbage/expired token	`get_current_user` → clean 401 with `WWW-Authenticate`
Request another user's expense id	Owner-scoped query → 404 (not 403 — don't confirm it exists)
Trigger an unhandled 500	Global handler → generic body + correlation id, full trace stays server-side
Request `limit=999999` to dump everything	`Query(le=100)` → 422
Read a secret out of "deleted" git history	Swept by filename and value across all branches → clean

Learning shortcut vs. production

I did (learning)	Production would
Manual curl audit, then automated it	Audit runs in CI on every push, blocks merge on a regression
5 focused tests	Broader coverage: every endpoint, edge cases, a real coverage target
In-memory `StaticPool` test DB	Same pattern scales fine — just more fixtures and factories
`print`/`logger` to stdout	Structured logging with levels + an alert on sustained 500s
Deferred prod CORS to Phase 9	Env-driven allowed origins, locked to the real frontend URL
Called the secret history "clean"	Rotate secrets anyway before a public deploy — rotation beats archaeology
Ignored the `httpx`/`httpx2` deprecation warning	Resolve it before it becomes a hard break on a dependency bump

None of these are wrong for where I am. They're known — written down, not pretended away.

Key habits to keep

Read the real output; don't trust that it worked. The $s log, the uncollected test, the capital-F login — every one was caught by observing, not assuming.
Prove the tooling before you trust the result. A smoke test against /health first means any later red is a real failure, not a setup problem.
collected N items is the first line you read. A green suite that silently skips a test is worse than a red one.
Strip the pipeline, read the raw response. A KeyError in a wrapper hides the {"detail": ...} that would've told you the answer.
Fixtures must clean up. A global dependency_override poisons every other test. yield + teardown keeps them isolated.
A 200 control prevents a false-pass 404. Prove the thing exists and that the wrong user can't see it.
Git history is permanent, and secrets leak by content, not filename. Sweep for the value across all branches, not just the file.
A filter matches strings, not meaning. alembic/env.py was innocent — always eyeball what matched.

Next up: Phase 9

The app is trustworthy now. The audit found no leaks, the unexpected 500 has a net, five tests lock in every guarantee that used to live only in my memory, and the git history is clean.

What's left is the last mile: getting it onto the internet. Phase 9 is deployment — starting with the one item I consciously deferred (production CORS, once I know the real frontend URL), then Render itself, where my own lessons come home to roost: Linux means venv/bin/activate, not Scripts/, and paths are case-sensitive (the capital-F login bug, now at the OS level). Secrets become real environment variables in a dashboard, not a .env file. And I'll confirm debug is off, closing the loop on the exception handler.

The features were the fun part. Turns out making them trustworthy was the part that actually taught me something.

See you in the next one.

silentcarry

Phase 7b — Bolting On the AI: An LLMCategorizer Behind the Same Door (with Caching, a Fallback, and Six Model Names)

Azhar Alvi — Sun, 09 Aug 2026 16:30:19 +0000

The seam I built in Phase 7a finally earned its keep.

I dropped a Gemini-backed categorizer in behind the exact same interface — main.py never noticed — with a config toggle, description-level caching so I'm not paying for the same "Starbucks" twice, and a rules fallback for when the model is down, slow, or wrong.

Here's the build, the six model names it took to get one working call, and the silent except block that hid a completely broken LLM for an embarrassingly long time.

Index

Where we left off
The plan: everything behind the same contract
Step 1 — The toggle: a factory and an env var
Step 2 — The stub: prove the wiring before the call
Step 3 — The real call: constrained prompt, validation, fallback
Step 4 — Caching: don't pay for the same Starbucks twice
One loose end: the CSV finally learned about categories
The war story: six model names and a comma
Thinking like an attacker
Learning shortcut vs. production
Key habits to keep
Next up: Phase 8

Where we left off

Phase 7a ended with a promise. I had a nullable category column, a dumb-but-honest rules engine, and — the part I actually cared about — a Categorizer Protocol with the rules implementation hiding behind it. I closed that post like this:

Now the fun part: an LLMCategorizer that satisfies the exact same Categorizer contract — so main.py never knows the difference — with a config toggle, per-merchant caching, and a rules fallback for when the model is slow, down, or just wrong. Phase 7b is where I find out if I actually earned it.

This is that. Spoiler: the seam held. The account quota is a different story.

The plan: everything behind the same contract

The temptation, again, was to reach straight for the API call and stuff it into categorize(). I didn't. I built outward from the safe end, one behavior-neutral step at a time:

Step	What	Why this order
1	A `CATEGORIZER` toggle + factory	One place decides rules-vs-LLM, defaults to rules — the app behaves identically until I flip it
2	An `LLMCategorizer` stub that returns `None`	Prove the toggle + wiring end-to-end with zero risk and zero cost
3	The real Gemini call, with validation + fallback	The risky external dependency goes in last, behind the seam
4	Description-level caching	Stop paying for the same description twice

The principle from 7a still drives it: build the boundary, then plug in the flaky thing. Every step until Step 3 leaves the app doing exactly what it did before. That's not caution for its own sake — it means when something finally breaks, I know it broke in the one thing I just changed.

Step 1 — The toggle: a factory and an env var

Right now the last line of categorization.py hard-codes the choice:

default_categorizer: Categorizer = RulesCategorizer()

That's fine for one implementation. But if I later scatter if CATEGORIZER == "llm" checks across main.py, I've made a mess. So I gave the decision a single owner — a factory: a function whose only job is to construct and hand back the right object based on config.

import os
from dotenv import load_dotenv

load_dotenv()  # read .env before we read any env vars


def get_categorizer() -> Categorizer:
    """Pick the categorizer based on the CATEGORIZER env var. Defaults to rules."""
    kind = os.getenv("CATEGORIZER", "rules").strip().lower()
    if kind == "llm":
        return LLMCategorizer()
    return RulesCategorizer()


default_categorizer: Categorizer = get_categorizer()

Two ideas clicked here:

Idea	Why it matters
`os.getenv("X", "rules")`	This is an optional setting with a safe default — same shape as my `DATABASE_URL` read. Contrast with `os.environ["X"]`, which I use for required secrets so the app fails loud if they're missing
Keep the name `default_categorizer`	`main.py` still does `from categorization import default_categorizer`. Rebinding it to `get_categorizer()`'s result means not one line of `main.py` changes — the call site stays blissfully ignorant

Env unset → "rules" → RulesCategorizer. The app behaves exactly like Phase 7a. Behavior-neutral seam, done.

Step 2 — The stub: prove the wiring before the call

Before I wrote a single line of Gemini code, I added a stub — a class with the right shape (it satisfies the Categorizer Protocol) but no real logic:

class LLMCategorizer:
    """LLM-backed categorizer. STUB for now: returns None until the real call is wired in."""

    def categorize(self, description: str) -> str | None:
        return None

Why bother stubbing when I could just write the real thing? Isolation. If I drop a live API call straight in and something misbehaves, I can't tell whether it's the wiring (env toggle → factory → app) or the call itself. The stub lets me flip CATEGORIZER=llm, restart, add a "swiggy" expense, and confirm it comes back Uncategorized — which proves the llm path is live and reaching my class. Zero cost, zero network.

And returning None is the correct stub behavior, not a placeholder shrug: my whole design treats None as "no category → NULL → Uncategorized." So a stub that categorizes nothing degrades to the exact same UX as the rules engine finding no match. Nothing breaks; the app just stops guessing while the stub is in.

Step 3 — The real call: constrained prompt, validation, fallback

This is the step the whole phase was building toward. Three non-negotiables went in together.

1. A constrained prompt. I don't let the model free-associate. It picks exactly one of my five existing categories, or the literal word None:

class LLMCategorizer:
    """LLM-backed categorizer using Google Gemini, constrained to the rules categories."""

    def __init__(self):
        api_key = os.environ["GEMINI_API_KEY"]  # fail loud if llm is on but no key
        self._client = genai.Client(api_key=api_key)
        self._allowed = set(CATEGORY_RULES.keys())
        self._fallback = RulesCategorizer()

    def categorize(self, description: str) -> str | None:
        categories = ", ".join(sorted(self._allowed))
        prompt = (
            "You are an expense categorizer. "
            f"Choose exactly ONE category for the expense from this list: {categories}. "
            "Reply with only the category name and nothing else. "
            "If it does not clearly fit any category, reply with the single word: None.\n"
            f"Expense description: {description}"
        )
        try:
            response = self._client.models.generate_content(
                model=GEMINI_MODEL,
                contents=prompt,
            )
            answer = (response.text or "").strip().strip(".").strip()
            for category in self._allowed:
                if answer.lower() == category.lower():
                    return category
            return None
        except Exception as e:
            print(f"[categorizer] LLM ERROR -> falling back to rules: {e!r}")
            return self._fallback.categorize(description)

Why constrain it to five categories instead of letting it invent its own? Because free-form output is data poison. Left alone, an LLM will happily return "Dining," "Restaurants," "Food & Drink," and "Meals" for four expenses that are all Food — and my future "spend by category" report splinters into meaningless buckets. A controlled vocabulary is what makes category-based reporting possible, and it keeps the LLM apples-to-apples comparable with the rules engine. Same five-word language, clean swap.

2. Never trust the output. LLMs drift: "Food.", " food", "**Food**". So I normalize (strip whitespace and a trailing period, compare case-insensitively) and only accept an answer that exactly matches one of my five. Anything else becomes None — the model declining to guess, which is the behavior I want.

3. Wrap the call and fall back to rules. Any failure — no network, quota exceeded, timeout, garbage response — must not break expense creation. On any exception I quietly return the rules answer.

Concept	What it does
Client built in `__init__`	Auth + connection set up once per instance, reused for every call — the factory returns a single `LLMCategorizer()`, so it's built once
`os.environ["GEMINI_API_KEY"]`	Fail loud: if `llm` is on but the key's missing, refuse to start. Only read when the factory actually builds the LLM path, so `rules` mode never needs it
`self._allowed = set(CATEGORY_RULES.keys())`	One source of truth — add a sixth rules category and the LLM's allowed list updates for free
`except Exception` → rules	Normally a code smell. Here it's deliberate: categorization is a non-critical enhancement that must never block the core POST

A bare except Exception catching everything is usually lazy. This one is a conscious trade-off — I'd rather an LLM outage silently degrade to rules than ever take down expense creation. But "silent" turned out to be the word that bit me. More on that in the war story.

Step 4 — Caching: don't pay for the same Starbucks twice

Every categorize() call hits Gemini, even for a description I've seen ten times. On a free tier, that's wasted latency and wasted quota. The fix is memoization — remember what an input mapped to, and on a repeat, return the stored answer with no API call:

def __init__(self):
    ...
    self._cache: dict[str, str | None] = {}

def categorize(self, description: str) -> str | None:
    key = description.strip().lower()
    if key in self._cache:
        return self._cache[key]

    # ... build prompt, call Gemini ...
    try:
        # ... get validated result ...
        self._cache[key] = result   # cache ONLY successful LLM outcomes
        return result
    except Exception as e:
        print(f"[categorizer] LLM ERROR -> falling back to rules: {e!r}")
        return self._fallback.categorize(description)  # never cached

Concept	What it does
A dict as cache	Key = normalized description, value = resolved category
`key = description.strip().lower()`	`"Uber"`, `"uber "`, `"UBER"` all hit the same entry — trivial differences shouldn't cost a call
In-memory	Lives on the instance, clears on restart. Acceptable for now; a DB/Redis cache is a later step
Cache only on success	The subtle one — see below

That last row is the one worth internalizing. The cache write lives inside the try, on the success path only. If the API errors and I fall back to rules, I must not store that. Picture Gemini down for a minute: I'd cache the fallback answer for "Starbucks" and keep serving it even after Gemini recovers. A poisoned cache outlives the outage. So fallbacks are never cached — ever.

The proof it worked, straight from the logs — I typed kFc, watched it call Gemini once, then added kFc again:

[categorizer] key='kfc' cache=['kfc']
[categorizer] CACHE HIT
INSERT INTO expenses ... (1.0, 'kFc', 'Food', '2026-08-09', 2)

Three things confirmed in four lines: the LLM genuinely ran (KFC isn't a rules keyword, yet it returned Food), normalization works (kFc → 'kfc'), and the repeat was served from cache with zero API calls.

One loose end: the CSV finally learned about categories

Small but real: my Phase 6 CSV export still wrote ["id", "description", "amount", "spent_on"] — it never knew the category column existed. A CSV export has two places that must agree: the header row and the data rows, and they're positional. Add a column to one, add it at the same index in the other, or every cell below shifts and the file is silently wrong:

writer.writerow(["id", "description", "category", "amount", "spent_on"])
# ...
writer.writerow([e.id, e.description, e.category, e.amount, e.spent_on])

A None category writes as a blank cell, which is the honest representation of "uncategorized." Now the category flows all the way from the model to the download.

The war story: six model names and a comma

Phase 7a's bugs were all about the four flavors of "nothing" — null vs "" vs omitted vs UTC-today. Phase 7b had its own theme: everything that isn't your code lying to you — config, the reload watcher, the environment, and a swallowed exception all conspired before I'd made a single real API call successfully.

Gotcha 1 — the comma that lived in my `.env`

I flipped the toggle on, restarted, added a "swiggy" expense... and it still came back Food. Was .env not being read? I stopped guessing and printed the value with !r:

print(f"[categorizer] CATEGORIZER={os.getenv('CATEGORIZER')!r}")
# [categorizer] CATEGORIZER='llm, '

There it is: 'llm, ' — a trailing comma and a space, baked into the value. In a .env file, everything after the = is literal, so my stray punctuation became part of the string. "llm, " == "llm" is False, the factory fell through to rules, and I got Food.

The lesson isn't "don't type commas." It's !r earns its keep. Without repr(), the log would've read CATEGORIZER=llm and I'd have sworn it was correct — the quotes are the only reason I saw the hidden ,. I later hardened the read with .strip().lower() so a stray space can't do this again (a comma still would — env values are exact).

Gotcha 2 — `--reload` doesn't watch `.env`

Before I found the comma, I'd been editing .env and waiting for uvicorn to pick it up. It never did. --reload only re-imports when a .py file changes. default_categorizer is bound once, at import, when get_categorizer() runs — so editing .env and saving does nothing until a true cold restart (Ctrl+C, then relaunch). The running process was holding the categorizer it built at its last real startup. Now "changed .env?" always means "cold restart," not "save and hope."

(VS Code chimed in here too, offering to load .env into the terminal via python.terminal.useEnvFile. Irrelevant — my code calls load_dotenv() and reads the file itself at runtime. Enabling it wouldn't have fixed anything. Dismissed.)

Gotcha 3 — "No module named 'google'" — the environment, not the folder

Installed google-genai, restarted, and: No module named 'google'. My first instinct was "wrong folder." Wrong instinct. pip install doesn't install into whatever directory you're standing in — it installs into whichever virtualenv is activated, landing in that venv's site-packages. The error meant the Python running uvicorn wasn't the same environment where the package landed. A reinstall in a properly-activated terminal fixed it instantly.

The mental model I locked in: a venv is a sealed box of packages; activating it points this terminal's pip/python at that box. No module named X = box mismatch. The one-line diagnostic is pip show <pkg> run in the terminal that runs the server — if it's not found there, the boxes don't match. (And a running process won't see a newly installed package until you restart it — same cold-restart discipline as Gotcha 2.)

Gotcha 4 — the silent `except` that hid a dead LLM

This is the big one, and it's the reason I now distrust quiet error handling. My fallback was working too well. Every test word I'd been using — uber, netflix, lunch — is also a rules keyword. So when the Gemini call failed and hit except → rules, I still got the "right" category and had no idea the LLM had never actually run. The safety net was masking a completely broken call.

The fix was to make the except talk instead of swallow:

except Exception as e:
    print(f"[categorizer] LLM ERROR -> falling back to rules: {e!r}")
    return self._fallback.categorize(description)

And the way to prove the LLM was genuinely working was to test with a word the rules engine doesn't know — Starbucks, KFC. If those come back categorized, only the model could have done it. Rules would've said Uncategorized.

Gotcha 5 — six model names

Once the except could speak, it immediately told me why nothing worked — a parade of failures across model names:

Model I tried	What the API said
`gemini-2.5-flash`	`404` — "no longer available to new users"
`gemini-2.5-flash-lite`	`404` — same gating for new keys
`gemini-2.0-flash`	`429 RESOURCE_EXHAUSTED`, `limit: 0` — free tier is zero on this model
`gemini-flash-latest`	Finally — a clean `generate_content`

The 429 was the sneaky one: limit: 0 doesn't mean "you used it up," it means "your key was never granted free-tier allowance for this model." That's an account/billing fact, not a code bug. The move that ended the guessing was to stop assuming model names and ask the key what it can do — client.models.list() prints every model available to you. Discover capabilities; don't hard-code hope.

I settled on the gemini-flash-latest alias. It's a moving target (it'll drift to newer models over time, which is bad for reproducibility), but a working alias beats a pinned name that 404s. Pinning a specific stable model is a known, deferred trade-off.

The through-line: before I'd made one successful API call, four different non-code layers had already lied to me — config, the reload watcher, the environment, and my own swallowed exception. The bug is rarely where you first look, and a silent except guarantees you'll look everywhere else first.

Thinking like an attacker

Same habit as always — actively try to break my own feature before reality does:

LLM returns "Food." with a period? .strip(".") + exact-match validation → still maps to Food.
LLM returns something off-menu like "Groceries"? Not in my five → None → Uncategorized. It can't invent a category and poison my data.
API is down mid-request? except → rules fallback → the expense still saves. Proven live when the 429 hit: the row saved as Uncategorized, the app didn't crash, the log named the reason.
Same "Starbucks" typed ten times? One API call, nine cache hits.
Gemini flaps during an outage? Fallback answers are never cached, so a recovered model isn't shadowed by a stale rules guess.

Learning shortcut vs. production

I did (learning)	Production would
In-memory dict cache	Persistent cache (DB/Redis) that survives restarts, with TTL
`gemini-flash-latest` alias	A pinned model version for reproducible behavior + cost
Free-tier key, `limit: 0` and all	Billing enabled (flash-lite is fractions of a cent) or a managed quota
`except Exception` catch-all	Catch specific API errors; alert on sustained fallback, not just log it
`print(...)` for the error	Structured logging with levels and a metric on fallback rate

None of these are wrong for where I am. They're known — written down, not pretended away.

Key habits to keep

Build the seam before the risky dependency. The Categorizer Protocol meant the LLM was a drop-in — main.py never changed. Phase 7a earned this; Phase 7b spent it.
Stub before you call. Prove the wiring with a None-returning placeholder before you introduce the network, the auth, and the quota all at once.
Never let except be silent. A swallowed error and a convenient fallback will hide a totally broken feature. Make it log.
Test with inputs your fallback can't fake. If rules and LLM would both say "Food," you've proven nothing. Use a word only the LLM could know.
Ask the system what it can do. models.list() beat four rounds of guessing model names.
!r when you print an env value. The quotes are how you catch the hidden comma.
Cache success, never failure. A poisoned cache outlives the outage that caused it.

Next up: Phase 8

The column holds a category. Rules fill it offline. The LLM fills it when it's on — behind the same door, validated, cached, and with a fallback that's now loud about failing. The human can still override all of it.

What's nagging me: the cache dies on every restart, the model name is a drifting alias, and my free tier can't actually afford to be the default. So Phase 8 is probably where I make the LLM path sustainable — a persistent cache, a pinned model, and a real answer to the quota question — or where I finally let categories drive the thing I've been building toward all along: reporting that actually means something.

The seam held. Turns out the hard part was never the code behind it.

See you in the next one.

— silentcarry

Phase 7a — Getting Opinionated: Rules-Based Auto-Categorization (and a Seam for the AI Later)

Azhar Alvi — Sun, 09 Aug 2026 06:32:37 +0000

My expense app finally has a point of view on what I'm spending money on. No AI yet — just honest keyword rules, a nullable column, and one interface that means I can bolt an LLM on later without ripping anything out. Here's the build, three "empty value" bugs that bit me, and the habits that kept it clean.

Index

Where we left off
The plan: rules first, AI behind the same door
Step 1 — A nullable column (and why nullable matters)
Step 2 — The migration: generate → review → apply
Step 3 — A dumb-but-working categorize()
Step 4 — Wiring it into create (with override precedence)
Step 5 — The seam: extracting behind a Categorizer interface
Step 6 — The UI loop: show, add, edit
🐛 The war story: three ways "empty" lied to me
Thinking like an attacker
Learning shortcut vs. production
Key habits to keep
Next up: Phase 7b

Where we left off

Phase 6 gave me the receipts — date-range reports and CSV export. I ended that post with a promise:

Next up: Phase 7, where categories finally enter the schema and the app starts to get opinionated about what I'm spending on.

This is that. But it turned into a bigger beast than one post, so I'm splitting it:

Phase 7a (this post): the schema, a rules-based categorizer, the interface seam, and the full UI loop.
Phase 7b (next): the actual LLM — an LLMCategorizer that slots in behind the same interface, with caching and a rules fallback.

Doing rules first isn't a cop-out. It's the whole strategy.

The plan: rules first, AI behind the same door

The temptation with "AI categorization" is to reach straight for the API key. I didn't. Here's the order I actually built in, and why:

Step	What	Why this order
1	Nullable `category` column	The app needs somewhere to store a category before it can fill one
2	Rules `categorize()`	A working, free, offline fallback — and a baseline to test against
3	Extract behind an interface	So the LLM can slot in later without touching call sites
4	UI loop (show / add / edit)	Give the human final say, no matter how smart the auto-fill gets
5	(Phase 7b) LLM implementation	The risky external dependency goes in last, behind the seam

The principle: build the boundary before you plug in the flaky thing. Rules are boring and reliable. The LLM will be clever and occasionally down, slow, or wrong. If both live behind the same contract, swapping between them — or falling back — is a one-line change.

Step 1 — A nullable column (and why nullable matters)

One new line on the Expense model:

category: Mapped[str | None] = mapped_column(String(50), nullable=True)

The interesting bit is the | None / nullable=True. Every expense already in my database was created before this column existed. If I made it nullable=False, the migration would try to force a value into all those existing rows and fail — or demand a default I don't actually want.

Nullable is honest: old rows are genuinely uncategorized. "No category" is a real state, not an error. And it maps perfectly onto the rules engine returning "I don't know" — more on that below.

New syntax I picked up here:

Syntax	Meaning
`Mapped[str]`	A required string
`Mapped[str \	None]`
`String(50)`	Length-bounded, like my `description` at 255

Step 2 — The migration: generate → review → apply

Three deliberate moves, not one:

# 1. Generate (does NOT touch the DB — just writes a script)
alembic revision --autogenerate -m "add category column to expenses"

# 2. Review — open the file, confirm it does EXACTLY one thing
#    upgrade() -> add_column('expenses', 'category', String(50), nullable=True)
#    downgrade() -> drop_column('expenses', 'category')   # reversible!

# 3. Apply (this one DOES modify the database)
alembic upgrade head

Autogenerate is good, not infallible. It occasionally invents spurious type tweaks, and SQLite has its quirks with certain operations. So I read the file every single time before applying — confirming both that upgrade() does only what I asked and that downgrade() cleanly reverses it.

Backup habit: SQLite is a single file, so a backup is a cp:

cp expenses.db expenses.backup.db
alembic upgrade head

Verified the column actually landed:

python -c "import sqlite3; print(sqlite3.connect('expenses.db').execute('PRAGMA table_info(expenses)').fetchall())"
# ...a 'category' row, VARCHAR(50), nullable. Existing rows: None.

(Aside: my .gitignore had *.db but not *.bak. Named the backup expenses.backup.db so the existing rule caught it, then added *.bak anyway as housekeeping.)

Step 3 — A dumb-but-working `categorize()`

No AI. Just keywords:

CATEGORY_RULES = {
    "Food": ["swiggy", "zomato", "restaurant", "cafe", "coffee", "pizza",
             "lunch", "dinner", "breakfast", "meal", "food", "grocery", "canteen"],
    "Transport": ["uber", "ola", "cab", "fuel", "petrol", "metro"],
    "Shopping": ["amazon", "flipkart", "myntra", "mall"],
    "Utilities": ["electricity", "water", "gas", "internet", "wifi", "recharge"],
    "Entertainment": ["netflix", "spotify", "movie", "bookmyshow"],
}

def categorize(description: str) -> str | None:
    text = description.lower()
    for category, keywords in CATEGORY_RULES.items():
        if any(keyword in text for keyword in keywords):
            return category
    return None

The concepts I actually learned writing this:

Concept	What it does
`.lower()`	Case-insensitive matching — `"UBER"`, `"Uber"`, `"uber"` all hit
`keyword in text`	Substring test — `"uber" in "uber to airport"` is `True`
`any(... for ...)`	Returns `True` on the first match, then stops
`return None`	No match = no guess — maps onto the nullable column

That last line is the design decision I'm proudest of. When the rules don't recognize something, they don't guess wildly — they return None, and the expense stays honestly uncategorized. Tested in isolation before wiring anything:

python -c "from main import categorize; print(categorize('Uber to airport'), '|', categorize('Swiggy dinner'), '|', categorize('Random mystery charge'))"
# Transport | Food | None

Step 4 — Wiring it into create (with override precedence)

The rule: if the user explicitly sends a category, respect it. Only auto-fill when they don't.

data = payload.model_dump()
if data.get("category") is None:
    data["category"] = categorize(data["description"])
expense = Expense(**data, user_id=current_user.id)

data.get("category") returns None if the key is missing or sent as null — my "did the user leave it blank?" test. Blank → auto-categorize. Provided → keep theirs.

This is also where the first landmine was waiting (see the war story). But conceptually: the client now has three honest options — omit it (auto), send a value (override), or send null (explicitly uncategorized).

Step 5 — The seam: extracting behind a `Categorizer` interface

This is the step that makes Phase 7b painless. Right now categorize() lives inside a web route — core domain logic welded to the HTTP layer. That's a smell, and it blocks the LLM work. So I pulled it into its own module behind a contract:

# backend/categorization.py
from typing import Protocol

class Categorizer(Protocol):
    """The contract every categorizer must satisfy."""
    def categorize(self, description: str) -> str | None:
        ...

class RulesCategorizer:
    """Keyword-rules implementation of the Categorizer contract."""
    def __init__(self, rules: dict[str, list[str]] = CATEGORY_RULES):
        self._rules = rules

    def categorize(self, description: str) -> str | None:
        text = description.lower()
        for category, keywords in self._rules.items():
            if any(keyword in text for keyword in keywords):
                return category
        return None

# The single instance the rest of the app imports.
default_categorizer: Categorizer = RulesCategorizer()

Three ideas clicked here:

A Protocol is a contract. "Anything called a Categorizer must have categorize(description) -> str | None." A class satisfies it just by having that method — no inheritance (structural typing). My future LLMCategorizer will satisfy the same contract for free.
A class carries state. A bare function can't remember things. The LLM version will need to — an API client, and eventually a per-merchant cache. So a class, with self._rules on the instance.
One entry point. Everything imports default_categorizer and calls .categorize(...), blissfully ignorant of how it works. Swapping rules → LLM becomes a one-line change in one place.

Then main.py just does:

from categorization import default_categorizer
# ...
data["category"] = default_categorizer.categorize(data["description"])

Refactor discipline: I shipped the extraction as a pure, behavior-neutral commit — same inputs, same outputs — and only then, in a separate commit, widened the Food keywords. Never mix a refactor with a behavior change in the same commit. When something breaks later, you want git bisect to land on one or the other, not a tangle of both.

Step 6 — The UI loop: show, add, edit

Auto-categorization is useless if the human can't see or override it. Three small React slices:

Show — a category pill per row, with a loud fallback for the ones the rules missed:

{expense.category ? (
  <span className="mt-1 self-start rounded-full bg-slate-100 px-2 py-0.5 text-xs font-medium text-slate-600">
    {expense.category}
  </span>
) : (
  <span className="mt-1 self-start rounded-full bg-red-100 border border-dashed border-slate-300 px-2 py-0.5 text-xs italic text-slate-400">
    Uncategorized
  </span>
)}

I made the "Uncategorized" pill red on purpose — it's a gentle nudge that says "this one still needs you."

Add — an optional category input on the create form, plus defaulting the date to today.

Edit — the same override on the inline edit form, so those red flags are actionable: click, type a category (or clear it), save.

Both forms share one trick that turned out to be load-bearing — which brings me to the bugs.

🐛 The war story: three ways "empty" lied to me

Phase 6 had one signature bug (a CSV that only wrote its last row, traced to an indentation slip). Phase 7a had a theme: every single bug this session was about the difference between null, empty string, omitted, and the wrong day. "Nothing" is not one thing. It's at least four, and they don't behave the same.

Gotcha 1 — Nullable ≠ optional (the silent 422)

I declared the create field like this and thought I was done:

# BROKEN — required, but allowed to be null
category: str | None

Omit category in the request body → 422 Field required. In Pydantic v2, | None only says "null is an allowed value." What makes a field skippable is a default.

# FIXED — truly optional
category: str | None = Field(default=None, max_length=50)

| None = "null is allowed." = None = "you can omit it." You need both for "optional and nullable." Two different questions; I'd only answered one.

Gotcha 2 — Empty string sneaks past the categorizer

My backend auto-fills only when category is None:

if data.get("category") is None:
    data["category"] = categorize(data["description"])

But an HTML text input never gives you None. Empty it, and it hands you "". So the naive form body...

// BROKEN — always sends a string, even when blank
body: JSON.stringify({ description, amount, spent_on: spentOn, category })

...sends category: "". And "" is None → False. So the backend treats an empty box as a deliberate override, skips categorize() entirely, and every blank-form expense silently lands uncategorized. My shiny new auto-categorization looked completely broken — because of a frontend empty string.

// FIXED — blank (or whitespace) becomes real null
body: JSON.stringify({
  description, amount, spent_on: spentOn,
  category: category.trim() || null,
})

"".trim() is falsy → || null kicks in → the backend sees None → auto-categorizes. .trim() also stops someone "overriding" with three spaces. I used the exact same line on the edit form, where clearing the box is how you send a category back to null.

Gotcha 3 — "Today" was yesterday (a UTC off-by-one)

I wanted the add form to default the date to today. The one-liner everyone reaches for:

// BROKEN — this is today in UTC
const today = new Date().toISOString().slice(0, 10);

toISOString() returns UTC. I'm in IST (UTC+5:30). So between midnight and ~5:30 AM my time, UTC is still on yesterday's date, and the form would confidently pre-fill the wrong day. A bug that only appears before breakfast is the worst kind.

// FIXED — build the string from LOCAL parts
function getTodayString() {
  const now = new Date();
  const year = now.getFullYear();
  const month = String(now.getMonth() + 1).padStart(2, "0"); // 0-indexed!
  const day = String(now.getDate()).padStart(2, "0");
  return `${year}-${month}-${day}`;
}

Same getMonth() + 1 / padStart pattern I'd already written for the CSV filename in Phase 6 — reused, not reinvented.

The through-line: null, empty string, omitted, and UTC-vs-local are four different flavors of "nothing/edge," and conflating any two of them is a bug. Now I check which kind of empty I'm actually dealing with.

Thinking like an attacker

The habit from earlier phases that keeps paying off — actively try to break my own feature:

Whitespace-only category? .trim() || null → treated as blank. ✅
value={null} on a controlled input? React silently switches the input to uncontrolled and warns. Coalesced the edit prefill with expense.category || "". ✅
Editing description shouldn't nuke the category. The update uses model_dump(exclude_unset=True), so omitted fields are left untouched. Sending only {"description": "..."} preserves the category. ✅
The substring trap I haven't fixed yet: "gas" is a keyword under Utilities — and it's a substring of "Ve*gas*". So "Vegas trip" categorizes as Utilities. This is the fundamental ceiling of keyword rules, and it's exactly the wall the LLM in Phase 7b is meant to break through. Logged, not hidden.

Learning shortcut vs. production

I did (learning)	Production would
Hardcoded `CATEGORY_RULES` dict	Config/DB-driven, editable without a deploy
Free-text category strings	A constrained enum or a `categories` table
`cp expenses.db expenses.backup.db`	Automated, tested DB backups + a restore drill
No re-categorize on description edit	Probably offer "re-run categorization" as an explicit action
Substring matching	Word-boundary matching, or skip straight to the model

None of these are wrong for where I am. They're just known — written down, not pretended away.

Key habits to keep

Build the seam before the risky dependency. The Categorizer interface exists so the LLM is a plug-in, not a rewrite.
One pure refactor per commit. Never bundle "moved code" with "changed behavior."
Review every migration before applying it. Autogenerate is a draft, not a decree.
Know which "empty" you mean. null ≠ "" ≠ omitted ≠ UTC-today. Four bugs wearing one costume.
Give the human the final say. However good auto-fill gets, the override is the point.
Log the limitations you're not fixing yet. "Vegas → Utilities" is a bug I chose to defer, not one I missed.

Next up: Phase 7b

The column holds a category. The rules fill it. The interface is ready. The human can override it everywhere.

Now the fun part: an LLMCategorizer that satisfies the exact same Categorizer contract — so main.py never knows the difference — with a config toggle, per-merchant caching so I'm not paying for the same "Starbucks" twice, and a rules fallback for when the model is slow, down, or just wrong. The whole point of the seam was to make that a drop-in. Phase 7b is where I find out if I actually earned it.

See you in the next one. — silentcarry

Phase 6 — Give Me the Receipts: Date-Range Reports & CSV Export in FastAPI

Azhar Alvi — Fri, 07 Aug 2026 18:26:51 +0000

Tagline: Let the database do the filtering, let Python do the formatting, and never hand-build a CSV.

Introduction

By the end of Phase 5 my app could already tell me how much I'd spent this month and whether I was up or down versus last month. Nice numbers on a dashboard. But numbers on a screen aren't something you can do anything with — you can't hand them to an accountant, drop them into a spreadsheet, or keep a copy.

So Phase 6 was about one deceptively small idea: let me pull my expenses for a date range, and let me download them as a CSV.

It sounds like a five-minute job. And the happy path is short. But doing it properly — query parameters that validate themselves, a file download that actually streams, and an authenticated button on the frontend — surfaced a few things that "just write an endpoint" glosses over. Here's what I actually did, and why, including the one bug that had me squinting at an indentation level.

Index

Structure of this log
Step 1: The date-range report endpoint (query parameters + validation)
Step 2: The CSV export endpoint (csv + StringIO + StreamingResponse)
The bug: my CSV only had one row
Step 3: Don't Repeat Yourself — extracting a shared helper
Step 4: The Export CSV button (why a plain link won't work)
Key habits to keep

Structure of this log

Add an authenticated, owner-scoped report endpoint that filters by an explicit start/end date range
Add a CSV export endpoint that streams a real file download
Refactor the shared logic into one helper so the two endpoints can't drift apart
Wire an Export CSV button into the React dashboard
Write down the snags and the "why", so future-me doesn't relearn them

Step 1: The date-range report endpoint

Every endpoint I'd built until now took either a JSON body (payload: ExpenseCreate) or a value baked into the URL path (expense_id in /expenses/{expense_id}). A report needs neither. It needs the caller to say "give me the expenses between these two dates." That's what query parameters are for — the ?key=value bits on the end of a URL:

GET /reports/monthly?start=2026-08-01&end=2026-08-31

The rule I learned for query params

In FastAPI, any function parameter that (a) isn't part of the path and (b) is a plain scalar type automatically becomes a query parameter, read from the URL. Give it no default value and it's required — FastAPI returns a 422 on its own if the caller leaves it out. No if not start: boilerplate needed.

Two layers of validation

This was the part I didn't want to skip.

Layer 1 — free validation from the type hint. By typing the params as date, FastAPI parses "2026-08-01" into a real Python date for me and auto-rejects garbage like "banana" or "2026-13-40" with a 422 before my function even runs. Same "let the types do the validating" lesson as Pydantic schemas, just applied to the URL.

Layer 2 — validation the types can't do. FastAPI can confirm each value is a valid date. It has no idea whether start is supposed to come before end. That's business logic, so I check it myself and raise a 400:

Status	When	Meaning
`422`	`start=banana`	The request is malformed — FastAPI can't even parse it
`400`	`start` after `end`	The request parsed fine, but it's logically wrong

The distinction matters: 422 is "I can't read this," 400 is "I read it, and it doesn't make sense."

Inclusive range vs the half-open trick

In Phase 5 I used half-open ranges (spent_on >= month_start AND spent_on < next_month_start) because the upper bound was "the start of the next month" — half-open is the clean way to not double-count a boundary.

Here it's different. The user hands me an end date they want included, and spent_on is a pure date column (no time-of-day to trip over). So the intuitive, correct choice is inclusive on both ends: >= start AND <= end. If I ask for Aug 1 to Aug 31, I expect Aug 31 in the result.

That's a genuine judgement call, not a rule to memorise: half-open when the boundary is "the start of the next period", inclusive when the user is naming the exact last day they mean.

The endpoint

@app.get("/reports/monthly", response_model=List[ExpenseRead])
def get_monthly_report(
    start: date,
    end: date,
    db: Session = Depends(get_db),
    current_user: User = Depends(get_current_user),
):
    if start > end:
        raise HTTPException(
            status_code=400,
            detail="start date must be on or before end date",
        )
    expenses = db.scalars(
        select(Expense).where(
            Expense.user_id == current_user.id,
            Expense.spent_on >= start,
            Expense.spent_on <= end,
        )
    ).all()
    return expenses

Everything else is the same owner-scoped select(...).where(Expense.user_id == current_user.id, ...) pattern I already trusted from list_expenses. The only new muscles are the query params and the 400 check.

How I tested it (the adversarial pass)

I don't just test the happy path any more — I try to break it the way a real user or an attacker would:

Happy path: start=2026-08-01, end=2026-08-31 → my August expenses.
Backwards dates → 400 with my message.
start=banana → 422, automatically, without my code running.
A month with no expenses → [], not an error.
No token → 401. (Owner-scoping means another user's rows never show up either.)

Step 2: The CSV export endpoint

Now the download. Three ideas I hadn't used before.

Idea 1 — the `csv` module

My first instinct was to build CSV text by hand with f-strings and commas. That breaks the first time a description contains a comma — Lunch, coffee would split into two columns and shift every field after it. Python's built-in csv module handles all the escaping: hand csv.writer a row as a list, and it writes a correctly-quoted line. The comma-in-your-data attacker loses for free.

Idea 2 — `io.StringIO`, a file that lives in memory

csv.writer needs something file-like to write into, but I don't want to create a real file on disk just to hand it back over HTTP. io.StringIO is an in-memory text buffer that behaves exactly like an open file. csv.writer writes into it, and then I read the text back out.

The one non-obvious line is buffer.seek(0) afterwards: writing leaves the cursor at the end of the buffer, so I rewind it to the start, or the response reads from the end and hands back nothing.

Idea 3 — `StreamingResponse` + download headers

A normal FastAPI return becomes JSON. To make the browser treat the reply as a downloadable file, I return a StreamingResponse with two things:

Piece	What it does
`media_type="text/csv"`	Tells the client "this is CSV, not JSON"
`Content-Disposition: attachment; filename="..."`	The `attachment` keyword is what makes the browser download and name the file instead of showing it inline

The endpoint

@app.get("/reports/monthly.csv")
def export_monthly_report_csv(
    start: date,
    end: date,
    db: Session = Depends(get_db),
    current_user: User = Depends(get_current_user),
):
    if start > end:
        raise HTTPException(
            status_code=400,
            detail="start date must be on or before end date",
        )
    expenses = db.scalars(
        select(Expense).where(
            Expense.user_id == current_user.id,
            Expense.spent_on >= start,
            Expense.spent_on <= end,
        )
    ).all()

    buffer = io.StringIO()
    writer = csv.writer(buffer)
    writer.writerow(["id", "description", "amount", "spent_on"])
    for expense in expenses:
        writer.writerow(
            [expense.id, expense.description, expense.amount, expense.spent_on]
        )
    buffer.seek(0)

    filename = f"expenses_{start}_{end}.csv"
    return StreamingResponse(
        buffer,
        media_type="text/csv",
        headers={"Content-Disposition": f'attachment; filename="{filename}"'},
    )

Note: csv, io, and StreamingResponse are all standard library or already shipped with FastAPI — no new packages, so requirements.txt didn't change.

Learning shortcut vs production version: I build the whole CSV in memory first, which is perfect for a personal expense tracker. For a huge export you'd yield rows from a generator so you never hold the whole file in RAM — same StreamingResponse, just fed a generator instead of a buffer. Good to know it exists; not needed yet.

The bug: my CSV only had one row

First download: header row, then… one expense. I had more than one in August, and Step 1's report endpoint (same query!) returned all of them. So the data wasn't the problem — the writing was.

The tell was which expense showed up. It was the last one. That points at exactly one thing: my writer.writerow(...) had drifted out of the for loop. Python happily ran the loop doing nothing, then wrote the loop variable — left pointing at the final expense — exactly once.

# BROKEN — writerow is dedented, so it runs once after the loop
for expense in expenses:
    ...
writer.writerow([expense.id, expense.description, expense.amount, expense.spent_on])

# FIXED — writerow is indented inside the loop, so it runs per expense
for expense in expenses:
    writer.writerow([expense.id, expense.description, expense.amount, expense.spent_on])

In a language where indentation is the block structure, a single wrong indent level isn't a style nit — it changes what runs when. Lesson filed: when a loop "only does the last thing once", check the indentation before you check anything else.

Step 3: Don't Repeat Yourself — extracting a shared helper

With both endpoints working, I noticed they now carried the identical validation-plus-query block. That's a maintenance trap: the day I change the date logic (say, exclude refunds later), I have to remember to change it in both places, and the bug is that I'll forget one.

So I pulled the shared work into a single helper — the one source of truth.

def _expenses_in_range(
    start: date,
    end: date,
    db: Session,
    current_user: User,
) -> list[Expense]:
    if start > end:
        raise HTTPException(
            status_code=400,
            detail="start date must be on or before end date",
        )
    return db.scalars(
        select(Expense).where(
            Expense.user_id == current_user.id,
            Expense.spent_on >= start,
            Expense.spent_on <= end,
        )
    ).all()

Two small things I learned here:

The leading underscore. I already knew _ as the throwaway-value convention. A leading underscore on a function name is a related-but-different convention: "this is an internal helper for this module, not a public endpoint." No decorator, so FastAPI never exposes it as a route.
Raising from a helper is fine. I worried the 400 might get swallowed. It doesn't — FastAPI catches HTTPException no matter how deep it's raised, so the status still reaches the client.

The report endpoint's body then collapses to a single line, and the CSV endpoint keeps only its CSV-building:

@app.get("/reports/monthly", response_model=List[ExpenseRead])
def get_monthly_report(start: date, end: date, db: Session = Depends(get_db), current_user: User = Depends(get_current_user)):
    return _expenses_in_range(start, end, db, current_user)

This was a "prove I changed nothing observable" refactor: I re-ran the same adversarial checks on both endpoints and confirmed identical behaviour. Green before, green after.

Step 4: The Export CSV button (why a plain link won't work)

Last piece — the button. My first instinct was a plain <a href="...monthly.csv" download>. That does not work here, and the reason is worth internalising: a normal link navigation can't attach an Authorization header. My CSV endpoint is owner-scoped and needs Bearer <token> — a bare anchor click sends no token, so it'd just get a 401.

So I do the download in the code path I actually control:

fetch the endpoint with the auth header (same as every other authed call).
Read the body as a Blob via response.blob() — a Blob is an in-memory chunk of file data, the right shape for a file (unlike response.json(), which I use for data).
URL.createObjectURL(blob) mints a temporary in-browser URL pointing at that blob.
Create an <a> in code, set href to that URL and the download attribute to the filename, then programmatically click() it.
URL.revokeObjectURL(url) frees the memory afterward — the object URL pins the blob in memory until revoked. Skipping it is a small leak (the "left the tap running" case).

async function handleExportCsv() {
  const token = localStorage.getItem("token");

  // Build the current month's range as YYYY-MM-DD strings.
  const now = new Date();
  const year = now.getFullYear();
  const month = now.getMonth(); // getMonth() is 0-indexed (Jan = 0)
  const pad = (n) => String(n).padStart(2, "0");
  const start = `${year}-${pad(month + 1)}-01`;
  const lastDay = new Date(year, month + 1, 0).getDate(); // day 0 of next month = last day of this one
  const end = `${year}-${pad(month + 1)}-${pad(lastDay)}`;

  const response = await fetch(
    `http://localhost:8000/reports/monthly.csv?start=${start}&end=${end}`,
    { headers: { Authorization: `Bearer ${token}` } },
  );

  if (response.status === 401) {
    onAuthError();
    return;
  }
  if (!response.ok) {
    console.error("Export failed", response.status);
    return;
  }

  const blob = await response.blob();
  const url = URL.createObjectURL(blob);
  const link = document.createElement("a");
  link.href = url;
  link.download = `expenses_${start}_${end}.csv`;
  document.body.appendChild(link);
  link.click();
  link.remove();
  URL.revokeObjectURL(url);
}

Two date lines earned a second look. getMonth() is 0-indexed, so I add 1 for display. And new Date(year, month + 1, 0) is the classic "last day of the month" trick — day zero of the next month rolls back to the last day of this one. padStart(2, "0") makes sure I send 08, not 8.

I also reused my existing 401 → onAuthError() pattern, so an expired token during export logs me out cleanly instead of silently failing — consistent with the rest of the app. Hand-rolling date strings is fiddly, though; letting the user pick the month (or using a date library) is a natural future upgrade.

Key habits to keep

Let the database filter, let Python format. The WHERE clause narrows the rows; Python only shapes what's left into CSV. Don't fetch everything and filter in a loop.
Types validate your inputs for free — use them. Typing a query param as date gave me parsing and a 422 on bad input with zero extra code. Reserve hand-written checks for the logic types can't express (like start <= end).
400 vs 422 is a real distinction. "I can't read this" is not the same as "I read it and it's wrong." Return the one that tells the caller the truth.
Never build a CSV by hand. The csv module exists precisely because commas and quotes in your data will bite you.
When a loop only does the last thing once, suspect the indentation. In Python, an indent level is control flow, not decoration.
DRY the moment you see the second copy. Two identical blocks is one bug waiting to be half-fixed. A tiny helper is cheaper than the drift.
A download that needs auth can't be a plain link. Fetch with the header, turn the response into a Blob, and trigger the download yourself.

Phase 6 turned a dashboard of numbers into something I can actually take with me. Next up: Phase 7, where categories finally enter the schema and the app starts to get opinionated about what I'm spending on.

Phase 5: The Numbers Start Talking

Azhar Alvi — Fri, 07 Aug 2026 05:50:47 +0000

My expense tracker could already remember everything.

It could register users, hash passwords, issue JWTs, isolate one user's expenses from another's, and do complete CRUD through a responsive React UI.

That was the end of Phase 4, Part 2: The Deviation: the app had a face, expired sessions returned me cleanly to login instead of leaving me stranded, the components had clearer jobs, and Tailwind had made the whole thing look less like a form recovered from an abandoned government portal.

Useful progress.

The code for this learning project lives in Smart Expense Manager on GitHub.

But the app still had no opinion.

It could show me every expense I had entered, but it could not answer the first question a normal person would ask an expense manager:

How much have I spent this month?

That is a different kind of feature.

CRUD asks the database to preserve and retrieve individual records.

Insights ask the database to look across many records and produce meaning.

So Phase 5 was where the app stopped being a digital shoebox and started becoming a dashboard.

Or at least that was the plan.

Because before I wrote the first aggregate query, the roadmap tried to make me invent data that did not exist.

The roadmap collision [the field I did not have]

My Phase 5 roadmap called for:

Total spent this month
Spend by category
Top merchants
Month-over-month comparison
A chart
Plain-language insights

Reasonable dashboard features.

One small problem: my Expense model did not have category or merchant fields.

It had:

id
user_id
amount
description
spent_on
created_at
updated_at

Category is not scheduled until Phase 7.

And description is not automatically a merchant just because both are strings. An expense described as Dinner after client meeting cannot honestly become a merchant named Dinner after client meeting because the roadmap would like a leaderboard.

This was the first decision of Phase 5, and no code was involved:

Do not manufacture a schema to make the roadmap look complete.

I could have pulled categorization forward, changed the database, created a migration, updated every schema and form, and turned one learning objective into six simultaneous changes.

That would have made the dashboard look busier.

It would also have destroyed the sequencing I had deliberately designed.

So I took the smallest vertical slice that used fields I actually had:

Calculate the authenticated user's total for the current month in SQL.
Verify it by hand.
Show it in React.
Make it refresh after CRUD changes.
Then compare the current month with the previous one.

Category spend, merchant rankings, and the category chart remain parked until the model can support them honestly.

Gotcha #15 — A roadmap dependency is not permission to lie to your model

This felt like a planning problem, but it was really a data-integrity problem.

A dashboard can only be as honest as the fields underneath it.

If the database does not distinguish a description from a merchant, the UI should not pretend it does.

The correct move was not to force Phase 5 to match every bullet immediately. It was to identify the dependency, document it, and build the valid slice first.

A roadmap is a guide.

The repository is ground truth.

The first real aggregate [let the database add]

Before this phase, most of my queries returned rows.

Find this expense.

List this user's expenses.

Update this row.

Delete that row.

A monthly total is different. I do not want every matching expense back. I want one value produced from all of them.

That is an aggregate.

The deliberately inefficient version would be:

Fetch all the user's expenses.
Move every row from SQLite into Python.
Loop through them.
Check each date.
Add each amount.

That would work on my tiny local database.

It would also teach the wrong habit.

Databases are built to filter and aggregate data. SQL can do the work close to where the data lives and return one number instead of shipping a pile of rows into application memory.

The shape I wanted was:

SELECT SUM(amount)
FROM expenses
WHERE user_id = ...
  AND spent_on >= ...
  AND spent_on < ...;

In SQLAlchemy 2.0, that became:

total = db.scalar(
    select(func.coalesce(func.sum(Expense.amount), 0)).where(
        Expense.user_id == current_user.id,
        Expense.spent_on >= month_start,
        Expense.spent_on < next_month_start,
    )
)

There are several ideas packed into that small block.

`func.sum(...)`

func is SQLAlchemy's bridge to SQL functions.

func.sum(Expense.amount)

means: ask the database to add the matching amount values.

Python is not performing that addition.

SQLite is.

`db.scalar(...)`

The query returns one cell: the total.

db.scalar(...) executes the statement and gives me that single value directly.

That is a better match than asking for a collection result and then digging one number out of it.

Owner scope still applies

The most important condition is easy to overlook because it is not mathematically interesting:

Expense.user_id == current_user.id

Without it, the total would combine every user's expenses.

The CRUD endpoints already close the IDOR hole by scoping records to the authenticated owner. Aggregate endpoints need the same discipline.

A dashboard number can leak data just as easily as a detail endpoint.

Possibly more quietly, because the user never sees the underlying rows.

Gotcha #16 — `SUM()` over no rows does not naturally give zero

My human expectation was simple:

No expenses means total spending is zero.

SQL's natural answer is different.

When SUM() has no matching rows, it returns NULL.

That is not the same as zero. NULL means there was no value to aggregate.

Useful database semantics; awkward dashboard semantics.

So I wrapped the sum with COALESCE:

func.coalesce(func.sum(Expense.amount), 0)

COALESCE returns the first non-null value.

If SUM() returns a real total, keep it.

If SUM() returns NULL, use 0.

The endpoint can now promise a number-shaped result even for a brand-new user.

I gave that result an explicit Pydantic response model:

class MonthlyTotalRead(BaseModel):
    total: Decimal

And the endpoint returns:

{
  "total": "6000.00"
}

The quotes are expected. My money values use Decimal, and they serialize as strings so JSON does not quietly introduce floating-point surprises.

The date filter [where most of the danger lived]

Adding numbers was the easy part.

Defining “this month” correctly was the part trying to become a bug.

A tempting filter is:

Expense.spent_on >= month_start

If the current month starts on August 1, that includes every expense from August 1 onward.

Including September.

And October.

And any future-dated expense I accidentally entered.

Gotcha #17 — A lower boundary without an upper boundary is not “this month”

The safe definition is a half-open range:

current_start <= spent_on < next_start

For August 2026:

August 1 <= spent_on < September 1

Why < September 1 instead of calculating the final date of August?

Because months have different lengths. The first date of the next month is a cleaner boundary than branching over 28, 29, 30, or 31 possible final dates.

If spent_on later becomes a timestamp, this same half-open-range idea will also avoid fragile end-of-day precision logic.

This is the same range idea I will reuse later for reports:

Include the start.
Exclude the next period's start.

No guessing about 28, 29, 30, or 31 days.

One helper, three boundaries [and my first useful tuple]

The monthly-total endpoint needed two dates:

Current month start
Next month start

The month-over-month endpoint would need three:

Previous month start
Current month start
Next month start

I could have copied the date logic into both endpoints.

That would work until one copy got fixed and the other did not.

So I moved it into a helper:

def get_month_boundaries(
    reference_date: date,
) -> tuple[date, date, date]:
    current_start = reference_date.replace(day=1)

    if current_start.month == 1:
        previous_start = date(current_start.year - 1, 12, 1)
    else:
        previous_start = date(
            current_start.year,
            current_start.month - 1,
            1,
        )

    if current_start.month == 12:
        next_start = date(current_start.year + 1, 1, 1)
    else:
        next_start = date(
            current_start.year,
            current_start.month + 1,
            1,
        )

    return previous_start, current_start, next_start

A tuple is an ordered, fixed collection of values.

The function needs to return three related dates, so it groups them into one tuple:

(previous_start, current_start, next_start)

Python lets me unpack that tuple by position:

previous_start, current_start, next_start = get_month_boundaries(
    date.today()
)

For the monthly-total endpoint, I do not need the first value:

_, month_start, next_month_start = get_month_boundaries(date.today())

The underscore is a normal variable with a conventional meaning:

This value exists, but I am intentionally not using it here.

The type hint:

tuple[date, date, date]

makes the contract visible: exactly three date values come back.

Gotcha #18 — January and December are not normal subtraction problems

This does not work in January:

current_month - 1

January is month 1. Month 0 does not exist.

December has the mirror problem when calculating the next month: month 13 does not exist.

That is why the helper has explicit rollover branches:

January 2026 previous start -> December 1, 2025
December 2026 next start   -> January 1, 2027

My current test data happened to be in August.

Production data will eventually arrive in January.

Calendar code that works only in the month it was written is not calendar code. It is a seasonal demo.

There is still one deliberate limitation: date.today() uses the backend machine's local date. For this local learning build, that is acceptable. A production version should define the application's business timezone explicitly so a user near a month boundary does not receive a total based on the server's calendar instead of their own.

Proving the total [not just admiring a 200]

The request returned HTTP 200.

That proved the route existed and the response matched the schema.

It did not prove the number was right.

So I checked the relevant expense amounts by hand and compared their sum with:

GET /insights/monthly-total

Then I created an adversarial row:

Description: Previous-month test
Amount: 999.99
Spent on: 2026-07-15

My current-month total had to remain unchanged.

It did.

Then I deleted only that temporary row.

This was the adversarial-testing habit—the project’s running “GAN analysis” joke—in its simplest useful form: give the query awkward data that should be rejected by its boundaries.

A test with only current-month expenses cannot prove that previous-month filtering works.

It only proves that current-month rows are included.

The rejected row was the evidence.

Putting the number in React [and keeping it alive]

The backend could answer the question now.

The user still had to open /docs to hear it.

So I added a monthly-total request inside ExpenseList's existing fetchExpenses() flow.

That placement was deliberate.

fetchExpenses() already runs:

When the expense screen loads
After adding an expense
After editing an expense
After deleting an expense

If the total is fetched in the same refresh path, it stays synchronized with the list without inventing another global state owner.

The state is local to the component that displays it:

const [monthlyTotal, setMonthlyTotal] = useState("0.00");

The intended authenticated request follows the same shape as the expense request. This is the corrected form I want the code to reach; the later source audit found that the committed file does not fully match it:

const totalResponse = await fetch(
  "http://localhost:8000/insights/monthly-total",
  {
    headers: { Authorization: `Bearer ${token}` },
  },
);

if (totalResponse.status === 401) {
  onAuthError();
  return;
}

if (!totalResponse.ok) {
  throw new Error(
    `Monthly total request failed: ${totalResponse.status}`,
  );
}

const totalData = await totalResponse.json();
setMonthlyTotal(totalData.total);

And the first dashboard metric became a small card:

<div className="mb-6 rounded-lg bg-blue-50 p-4">
  <p className="text-sm font-medium text-blue-700">
    Spent this month
  </p>
  <p className="mt-1 text-3xl font-bold text-blue-900">
    {monthlyTotal}
  </p>
</div>

I tested it with another temporary expense:

Description: Monthly metric refresh test
Amount: 1.00
Spent on: 2026-08-07

The total increased by exactly 1.00 without a manual page refresh.

Then I deleted the temporary row and watched the total return.

That was the point where the dashboard stopped being decoration.

It was now a live projection of database state.

Month-over-month [two totals, one comparison]

The next valid roadmap item was month-over-month comparison.

The endpoint needed four values:

class MonthOverMonthRead(BaseModel):
    current_month_total: Decimal
    previous_month_total: Decimal
    change_amount: Decimal
    change_percentage: Decimal | None

The database still performs the aggregation.

One query sums the previous-month range:

previous_total = db.scalar(
    select(func.coalesce(func.sum(Expense.amount), 0)).where(
        Expense.user_id == current_user.id,
        Expense.spent_on >= previous_start,
        Expense.spent_on < current_start,
    )
)

A second query sums the current-month range:

current_total = db.scalar(
    select(func.coalesce(func.sum(Expense.amount), 0)).where(
        Expense.user_id == current_user.id,
        Expense.spent_on >= current_start,
        Expense.spent_on < next_start,
    )
)

Then Python compares the two already-aggregated numbers:

change_amount = current_total - previous_total

This is an important boundary between database work and application work.

SQL is good at finding and summing the relevant rows.

Python is good at applying the small piece of business logic to the two totals.

I am not hauling raw expenses into Python to recreate SUM() badly.

I am combining two scalar results.

The percentage trap [zero has opinions]

The percentage formula is ordinary:

(current - previous) / previous × 100

The denominator is not ordinary when the user had no expenses last month.

Gotcha #19 — “No previous spending” is not a zero-percent change

Suppose:

Previous month: 0
Current month: 6000

It is tempting to say spending increased by 100%.

It did not.

There is no finite percentage that turns zero into 6000, because the formula requires division by zero.

Python will reject that calculation, and mathematically it is undefined.

So the endpoint handles that state explicitly:

change_percentage = None

if previous_total != 0:
    change_percentage = round(
        (change_amount / previous_total) * 100,
        2,
    )

The JSON response uses null when there is no valid percentage baseline:

{
  "current_month_total": "6000.00",
  "previous_month_total": "0",
  "change_amount": "6000.00",
  "change_percentage": null
}

That gives the frontend enough information to say something honest:

no previous-month spending to compare

Not 0% change.

Not 100% increase.

Not Infinity%, which would at least be memorable.

Signed data versus human language

With real previous-month data, the endpoint might return:

{
  "current_month_total": "6000.00",
  "previous_month_total": "10000.70",
  "change_amount": "-4000.70",
  "change_percentage": "-40.00"
}

The math is correct:

6000.00 - 10000.70 = -4000.70

And:

-4000.70 / 10000.70 × 100 ≈ -40%

But displaying this:

-4000.70
40% less than last month

felt clumsy.

The negative sign and the word less communicate the same direction twice.

Gotcha #20 — Correct data can still be unclear UI

The backend should preserve the signed value because the sign is useful for logic.

The frontend can present its absolute magnitude because the words provide the direction.

So the amount display became:

{Math.abs(Number(monthComparison.change_amount)).toFixed(2)}

Three small transformations:

Number(...) converts the API's decimal string into a JavaScript number.
Math.abs(...) removes the sign for presentation.
toFixed(2) displays exactly two decimal places.

The API remains truthful:

-4000.70

The card becomes readable:

4000.70
40% less than last month

Data representation and presentation are related, but they are not the same job.

The plain-English helper [let the card speak]

The comparison API returns one object containing related values, so React stores it as object state:

const [monthComparison, setMonthComparison] = useState(null);

null means the request has not produced data yet.

The card renders only when the object exists:

{monthComparison && (
  // comparison card
)}

For the text, I used a small pure helper:

function buildComparisonText(comparison) {
  if (comparison.change_percentage === null) {
    return "no previous-month spending to compare";
  }

  const percentage = Number(comparison.change_percentage);

  if (percentage > 0) {
    return `${Math.abs(percentage)}% more than last month`;
  }

  if (percentage < 0) {
    return `${Math.abs(percentage)}% less than last month`;
  }

  return "Spending is unchanged from last month";
}

A pure helper receives data and returns a result. It does not change React state, call the API, or mutate the input.

That makes the possible messages explicit:

More than last month
Less than last month
Unchanged
No valid previous-month baseline

The frontend is no longer just printing an aggregate.

It is interpreting it for a person.

That was one of the actual Phase 5 goals: plain-language insight statements, not just a number farm.

The second adversarial test [make the card move]

I reused the controlled previous-month row:

Description: Comparison refresh test
Amount: 100.00
Spent on: 2026-07-15

That row had to do several things at once:

Appear in previous_month_total.
Stay out of current_month_total.
Change change_amount correctly.
Produce a valid percentage instead of null.
Refresh the React card automatically after creation.
Return the card to its original state after deletion.

It passed all six.

This is the part of testing I am beginning to appreciate: one carefully chosen row can challenge several assumptions at once.

Then I ran:

npm run lint

And from the repository root:

git diff --check

Both passed during the feature work.

I committed the backend and frontend slices separately so the history preserved the vertical progression:

Add monthly spending total endpoint
Show monthly spending total in dashboard
Add month-over-month spending insight
Add month-over-mmonth dashboard insight

Yes, the final commit subject contains mmonth.

Git is a historical record, including the part where my fingers became optimistic.

I am not rewriting published history over a spelling mistake.

The audit after the victory lap [source code gets the final vote]

This article would be dishonest if it ended with “everything is hardened and perfect.”

When I reread the actual repository to prepare this write-up, I found several narrow cleanup items that the happy-path tests had not exposed.

The important one:

My previous article said I had placed the 401 guard into all authenticated calls, including update.

The current repository shows that handleUpdate() does not have the same explicit 401 branch before its generic failure path.

I do not know whether that guard was lost during a later edit or whether my earlier statement outran the committed code.

I do know which source wins the disagreement.

The repository.

I also found smaller issues in ExpenseList.jsx:

roundded-xl
text-3x1
Comapred with last month

And one broken error-message interpolation:

`Monthly total request failed: $(totalResponse.status)`

The interpolation syntax should use braces:

`Monthly total request failed: ${totalResponse.status}`

There is also one loose status comparison using == where === is clearer and safer.

Gotcha #21 — Passing the happy path does not mean the source is clean

None of those typos stopped my normal insight flow from working.

That is exactly why they survived.

A misspelled Tailwind utility is ignored rather than crashing React.
A misspelled label still renders.
A broken error string stays hidden until that error branch runs.
A missing 401 branch stays invisible while the token remains valid.

This is the adversarial lesson arriving late but usefully:

Code paths I did not trigger still deserve inspection.

So the next session begins with a narrow QA cleanup before Phase 6.

Not a giant refactor.

Not a shame spiral.

One focused correction at a time, with the same test-and-commit discipline.

The point of build-in-public is not to create the illusion that every checkpoint was flawless.

It is to preserve what I learned when the flaw became visible.

What Phase 5 actually completed

With the current schema, the app can now answer:

How much did this authenticated user spend this month?
How much did they spend in the previous month?
What is the signed difference?
What is the percentage change when a valid baseline exists?
Is spending higher, lower, unchanged, or not yet comparable?

The dashboard updates those answers after expense mutations.

The database performs the aggregation.

The API remains owner-scoped.

The frontend translates the result into language.

What Phase 5 did not complete:

Spend by category
Top merchants
Category chart

Those remain blocked by the schema, not forgotten.

Category arrives in Phase 7.

Merchant does not exist yet as a real field.

I am leaving both visible in the backlog rather than disguising descriptions as merchant data.

The mental model I am keeping

The biggest lesson was not the syntax of SUM().

It was the division of responsibility:

Database:
Find the correct owner's rows inside exact date boundaries and aggregate them.

Backend:
Define the business comparison, handle undefined cases, and return a stable schema.

Frontend:
Fetch the result, keep it synchronized, and translate signed data into readable language.

Or, shorter:

SQL finds and adds. Python decides. React explains.

That is the first architecture sentence I have written in this project that feels genuinely reusable.

Stuff I want to remember [the honest takeaways]

An aggregate turns many rows into one result.
Let the database perform SUM() instead of fetching every row into Python.
db.scalar(...) is the right shape when the query returns one value.
SUM() over no rows returns NULL; COALESCE(..., 0) gives the dashboard a usable zero.
Aggregate endpoints need owner scoping just as much as CRUD endpoints.
“This month” needs both boundaries: >= current_start and < next_start.
Half-open ranges avoid month-length and end-of-day traps.
January and December require explicit year rollover.
A tuple can return several fixed, ordered values from one helper.
Tuple unpacking assigns by position; _ conventionally marks an intentionally unused value.
SQL should aggregate the rows; Python can compare the resulting scalar totals.
Percentage change from a zero baseline is undefined, not automatically 0% or 100%.
Preserve signed values in the API when they are useful for logic.
Presentation can use an absolute value when words already communicate direction.
Object state is useful when one API response contains several related values.
A small pure helper can turn numeric states into predictable user-facing language.
Put insight fetching in the existing refresh flow if the metrics must update after CRUD mutations.
Test rejection boundaries with deliberately awkward data, not only happy-path rows.
A 200 proves the endpoint responded; hand calculation helps prove the number.
A passing happy path does not inspect dormant error branches.
The repository outranks an article, handoff, roadmap, or memory when they disagree.
A roadmap dependency is not permission to invent data.
Commit at green checkpoints, subject plus why.
Do not rewrite public Git history just to hide a typo.

Next up: Phase 6 [make the data leave the app]

The next roadmap phase is reporting and CSV export.

The planned vertical path is:

Add an authenticated, owner-scoped report endpoint filtered by a date range.
Verify that range manually.
Generate CSV with Python's csv module.
Return it as a streaming response with download headers.
Add an Export CSV button in React.

But first: the narrow QA cleanup this article's source audit exposed.

Because the app has learned to answer questions now.

Before I teach it to export those answers, I want every error path to tell the truth too.

The digital shoebox has become a dashboard.

Next, it becomes a report.

Phase 4 [Part 2] : The Deviation

Azhar Alvi — Sun, 02 Aug 2026 15:05:28 +0000

Kill the 30-minute dead-end where an expired token traps you on a broken screen, break one bloated component into smaller ones that each own their job, and give the login and app shell their first real coat of paint — the two debts I flagged at the end of Part 1, plus the refactor that made fixing them possible.

At the close of Part 1, my app finally had a face: I could log in through a real form and do full CRUD without ever opening /docs. Genuinely a milestone. But I ended that write-up with two honest confessions taped to the fridge. One: the login silently dies after 30 minutes — my JWTs expire, and when they do, the app just shows a confusing error and strands you, still pretending you're logged in. Two: it looked like a 1998 government form. A raw list, no styling, no polish.

I said I'd deal with both in "Phase 5." I changed my mind again.

A second confession: I pulled two Phase-5 jobs forward [and picked up a third I didn't plan]

Building a dashboard on top of a frontend that (a) traps users on a dead session, (b) crams everything into two god-components, and (c) is visually unusable felt like laying a nice floor over a cracked foundation. So before any new features, I spent a session paying rent on the foundation.

And here's the honest part: only one of these three jobs was on my list. The expired-token fix, yes — I'd flagged it. But chasing that bug is what dragged the props refactor in behind it, because the fix literally couldn't be written cleanly until I'd split my components up. One debt exposed another. That happens a lot, I'm learning.

Let's call it PHASE 4, PART 2 — Paying the Rent:

Reproduce the expired-token dead-end on purpose [without waiting 30 minutes]
Detect a 401 on any request and force a clean re-login
Learn props for real — by passing a function down so a child can trigger the parent's logout
Split App and ExpenseList into <LoginForm> and <AddExpenseForm>
Install Tailwind v4 [which is nothing like the tutorials you'll find]
Style the login into a centered card and the app into a dashboard shell
Make an honest call about a lint warning instead of cargo-culting a "fix"

Debt #1: the 30-minute dead-end [expired-token hardening]

Here's the flaw, stated plainly. My login issues a JWT with a 30-minute self-destruct baked in [the exp claim — Phase 3 me set that on purpose]. After 30 minutes the token is dead, and my FastAPI backend will reject any authenticated request — list, add, edit, delete — with a 401 Unauthorized. That's not a bug; that's the security feature working exactly as designed.

The bug was my reaction to it. My fetchExpenses caught any bad response as a generic "Could not load expenses," and my mutation handlers just console.error-ed the status. Meanwhile App still had a truthy token in state, so it kept rendering the logged-in view. The token was dead, but the app cheerfully pretended I was alive — an error message, a Logout button, and no automatic way out. A dead-end.

First move, and this is the adversarial habit surviving without the GAN framing: I reproduced the failure on purpose instead of waiting half an hour. DevTools → Application → Local Storage → double-click the token value → jam a few junk characters onto the end → hit an endpoint. An invalid token gets the exact same 401 an expired one would. Instant, repeatable bug. Watching it fail on demand is what made the fix obvious.

Then I hit the wall that turned this into a bigger job than expected:

The logout logic lived in the wrong place to fix this. My handleLogout [localStorage.removeItem('token') + setToken(null)] sits in App, the parent. But the 401 happens inside ExpenseList, the child. A child component cannot reach up and grab its parent's functions on its own. So how does the child tell the parent "the session is dead, log us out"? That question is what forced me to finally learn props — see the next section. The short version of the answer: the parent hands the child a function to call.

With that wired (details below), the fix inside each authed request was tiny and identical — check for 401 first, and if you see it, bail:

if (response.status === 401) {
  onAuthError();   // a function App passed down; it runs handleLogout
  return;
}

Gotcha #9 — a 401 is a subset of "not ok," so you have to catch it before your generic error branch. My old code did if (!response.ok) throw .... If I'd let that run first, every expired token would just show "Could not load expenses" and never log me out. By checking response.status === 401 first and return-ing, I short-circuit: onAuthError() flips token to null up in App, App stops rendering ExpenseList, and the login screen takes over. Order matters. Specific case before general case.

I dropped that same three-line guard into all four authed calls — fetchExpenses, handleAdd, handleDelete, handleUpdate — and while I was crawling through handleDelete, I found a landmine:

Gotcha #10 — a one-letter case typo that "works" only by luck. My delete URL read http://Localhost:8000 — capital L. It had been working the whole time because Windows treats hostnames case-insensitively, so Localhost resolves fine on my machine. The moment I deploy the backend to a Linux box [Phase 9], that could bite. Fixed it to lowercase localhost now, while I was in the neighborhood. Lesson: "it works on my machine" and "it's correct" are not the same sentence.

The payoff: I re-ran my sabotage — logged in, corrupted the token, triggered a request — and instead of the stuck error screen, the app bounced me straight back to the login form. Tested it from a reload and from the add button, to prove the guard fires from more than one place. The session can no longer lie to me.

The cleanup I didn't plan on: props [the refactor]

Remember the wall above — the child couldn't reach the parent's logout. The clean answer to that is the single most important React concept I'd been avoiding: props.

Props are how a parent hands things down to a child — data, config, or [the part that unlocks everything] functions. And the mirror image is the pattern that fixed my bug: a child reports an event up by calling a function its parent passed down. That's it. Data flows down; events flow up as function calls. My onAuthError was my very first one — App handed ExpenseList its handleLogout, renamed onAuthError for clarity, and the child calls it when it smells a dead session.

// In App: hand the function down
<ExpenseList onAuthError={handleLogout} />

// In ExpenseList: receive it
function ExpenseList({ onAuthError }) {

That { onAuthError } in the function signature stopped me for a second, so I'll pin down what it is:

{ } in a component's arguments is object destructuring — the cousin of the [ ] I already knew from useState. React always calls my component with one argument: a single object holding all its props. { onAuthError } reaches into that object and pulls out the onAuthError key by name. Contrast: useState gives me const [value, setter] — array destructuring, which unpacks by position [that's why order matters there]. Objects unpack by name, so the name inside the braces must exactly match the prop I passed. A typo like { onAuthErr } just silently hands me undefined.

Once I understood props, the mess I'd been living in became obvious: my login form was welded inside App, and my add-expense form was welded inside ExpenseList. Two components doing three jobs each. So I split them out, and I picked a deliberate design rule for both:

Each form owns its own state and does its own API call, then reports the result up through a callback prop. The parent stays thin and owns only what's genuinely shared. App doesn't care about my email or password keystrokes — it only cares "did we get a token?" So LoginForm keeps its own email/password state, does the login fetch itself, and calls onLoggedIn(token) on success. This is colocation: keep state as close as possible to where it's used, and lift up only the thing that's actually shared [the token].

function LoginForm({ onLoggedIn }) {
  const [email, setEmail] = useState("");
  const [password, setPassword] = useState("");

  async function handleSubmit(event) {
    event.preventDefault();
    const formBody = new URLSearchParams();
    formBody.append("username", email);
    formBody.append("password", password);

    const response = await fetch("http://localhost:8000/auth/login", {
      method: "POST",
      headers: { "Content-Type": "application/x-www-form-urlencoded" },
      body: formBody,
    });

    if (response.ok) {
      const data = await response.json();
      onLoggedIn(data.access_token);   // report success UP to App
    } else {
      console.log("Login Failed:", response.status);
    }
  }
  // ...the form JSX
}

App shed all the login state and shrank to a coordinator — it now owns only the token plus two tiny handlers:

function handleLoginSuccess(newToken) {
  localStorage.setItem("token", newToken);   // the side-effect stays with the owner of the token
  setToken(newToken);
}
function handleLogout() {
  localStorage.removeItem("token");
  setToken(null);
}

<AddExpenseForm> came out the same way, except it needs two callbacks: onAdded [it succeeded — parent, please re-fetch the list] and onAuthError [the 401 guard]. And that surfaced a nice, normal wrinkle:

Prop-forwarding is fine and expected. ExpenseList receives onAuthError from App, and then passes it one level deeper to AddExpenseForm. A prop can be handed down through multiple layers. <AddExpenseForm onAdded={fetchExpenses} onAuthError={onAuthError} /> — notice onAdded={fetchExpenses} is me passing ExpenseList's own re-fetch function down so the child can trigger a refresh after a successful add. Same function, reused through a prop.

Two more real things fell out of the refactor:

Gotcha #11 — moving JSX into a child leaves leftovers in the parent. The instant I extracted <LoginForm>, my login screen showed the title twice. Cause: I'd put the <h1>Smart Expense Manager</h1> inside LoginForm, but App was still rendering its own old heading right above it. This is the exact same lesson as the stray-render leak from Part 1 — when you restructure, hunt the leftovers. The fix doubled as a design decision: the app title is shell UI, so it belongs in App, exactly once. LoginForm renders only the form.

Gotcha #12 — the tempting lint "fix" is an infinite-loop trap. ESLint started nagging: "React Hook useEffect has a missing dependency: 'fetchExpenses'." The obvious move is to obey it and write }, [fetchExpenses]). Don't. fetchExpenses is a plain function, so React creates a brand-new copy of it every render. Put it in the dependency array and the effect thinks its dependency changed on every render → it re-fetches → setState re-renders → new function copy → fetches again → infinite loop. My empty [] is actually the behavior I want [run once on mount]. So I made a real decision instead of cargo-culting: I left the warning alone. It's a warning, not an error, and the code is correct. I didn't even add an eslint-disable comment — that would just be decorating a non-problem. [The genuinely-correct fix is wrapping the function inuseCallbackso its identity is stable — but that cascades into memoizing the callbacks I pass down too, which is more machinery than a beginner project needs right now. useCallback = "know this exists."]

The whole app behaves identically after all this — same login, same CRUD, same 401 bounce. But App and ExpenseList are now thin coordinators, and each form is a small thing that owns its one job. That's the entire point of the refactor: no new features, just a codebase I can actually keep building on.

Debt #2: it looked like a 1998 government form [Tailwind]

Time to make it not-ugly. I chose Tailwind CSS [utility-first styling] and a modern SaaS-dashboard look — soft-gray canvas, white cards with subtle shadows, a top header bar. Partly because it's everywhere in industry, partly because that card-and-shell layout is a direct warm-up for the Phase 5 dashboard.

First lesson before I typed a single class:

Gotcha #13 — Tailwind v4 threw out the setup every tutorial still teaches. Search "install Tailwind" and you'll get v3 instructions: a tailwind.config.js, a content: [...] array, @tailwind base/components/utilities directives, PostCSS wiring. In v4, all of that is gone. It's now a Vite plugin plus a single line of CSS. I actually verified the current steps against today's docs instead of trusting my memory or an old blog — which is a habit I want to keep for fast-moving tools, because copying stale setup is a guaranteed hour lost.

The entire v4 setup, for a Vite + React app:

npm install tailwindcss @tailwindcss/vite

// vite.config.js — ADD the plugin, keep react()
import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'
import tailwindcss from '@tailwindcss/vite'

export default defineConfig({
  plugins: [react(), tailwindcss()],
})

/* src/index.css — this ONE line replaces all the old @tailwind directives */
@import "tailwindcss";

A restart of the dev server later [config changes don't hot-reload — one to remember], I dropped className="text-3xl font-bold text-blue-600" on my title, watched it go big and blue, and knew the pipe was live. Note it's className, not class — the same JSX rule that bit me back in Part 1, now paying dividends because every Tailwind style rides on className.

The mental model that made Tailwind click: you don't write CSS rules in a separate file. You compose a look out of tiny, single-purpose utility classes right on the element — p-8 is padding, rounded-xl is corners, shadow-md is a shadow, bg-white is the background. Honest reaction: the className strings get long and repetitive, and my two login inputs share an identical one. That felt wrong at first, but it's genuinely idiomatic Tailwind. [Later I can collapse a repeated set with@applyin CSS, or extract a tiny<Input>component. Know this exists; not now.]

Here's the login screen — a centered white card floating on a gray page:

// App's logged-out branch
<div className="min-h-screen bg-slate-100 flex items-center justify-center">
  <div className="w-full max-w-sm bg-white rounded-xl shadow-md p-8 flex flex-col gap-6">
    <h1 className="text-2xl font-bold text-slate-800 text-center">Smart Expense Manager</h1>
    <LoginForm onLoggedIn={handleLoginSuccess} />
  </div>
</div>

The handful of utilities I'll actually reuse forever:

flex items-center justify-center — the centering combo. items-center centers vertically, justify-center horizontally. Wrap it in min-h-screen so there's a full viewport to center within.
flex flex-col gap-* — stack children in a column with even spacing between them, no margins to hand-tune.
focus:ring-2 / hover:bg-blue-700 — the focus: and hover: prefixes apply a style only in that state. It's Tailwind's answer to CSS pseudo-classes, and it's genuinely elegant — my inputs get a blue focus ring, my button darkens on hover, all inline.

Then the logged-in shell — a real SaaS layout with a header bar and a centered content column:

<div className="min-h-screen bg-slate-100">
  <header className="bg-white shadow-sm">
    <div className="max-w-3xl mx-auto px-6 py-4 flex items-center justify-between">
      <h1 className="text-xl font-bold text-slate-800">Smart Expense Manager</h1>
      <button onClick={handleLogout} className="text-sm text-slate-600 border border-slate-300 rounded-md px-3 py-1.5 hover:bg-slate-50 transition-colors">
        Logout
      </button>
    </div>
  </header>
  <main className="max-w-3xl mx-auto px-6 py-8">
    <ExpenseList onAuthError={handleLogout} />
  </main>
</div>

Two things worth banking here:

<header> and <main> instead of <div>s. These are semantic HTML — they render identically but tell browsers and screen readers what each region is. A free accessibility and clarity win; a small habit that separates "works" from "professional."
max-w-3xl mx-auto is the centered-column pattern. max-w-3xl caps the width so content isn't a painfully wide ribbon on a big monitor; mx-auto sets left/right margins to auto, which centers the block. I used the same max-w-3xl mx-auto px-6 on both the header's inner div and <main>, which is what keeps the logo and the content aligned down the page. justify-between in the header shoves the title hard-left and Logout hard-right.

And one small stumble that taught the right instinct:

Gotcha #14 — reach for gap on the parent, not a margin on each child. My title and the email box were jammed together with no space. My first instinct was to slap a margin-bottom on the heading. The cleaner fix — and the more Tailwind-idiomatic one — was to make the card a flex flex-col gap-6 container, so the gap spaces every child uniformly [title → form] with one declaration on the parent. Set the rhythm once, up top, instead of hand-tuning margins on each element and fighting margin quirks.

Honest status: this is the pass I've started, not finished. The login card and the whole app shell are dressed and look legitimately decent. What's not done yet: the expense-list itself is still raw inside that nice shell — the list needs to become a card, the add-expense form needs the same input/button styling as login, and each row needs tidy edit/delete buttons and clean loading/empty/error states. That's the frontier, and it flows directly into Phase 5.

The shape of every React conversation [the model that tied it together]

If Part 1's big mental model was "the Save button doesn't save — it asks the backend to," Part 2's is smaller but just as clarifying:

Data flows down, events flow up, and only a state change repaints the screen.

A parent passes data or functions down to a child as props.
When something happens in the child [login succeeded, a 401 came back, an expense was added], the child calls a function the parent gave it — that's the event flowing back up.
That function, running in the parent, changes state [setToken(...)]. And state changing is the only thing that makes React re-render and swap the screen.

Every single thing I built this session is that loop. LoginForm → onLoggedIn(token) → setToken → the UI flips to logged-in. ExpenseList → onAuthError() → setToken(null) → the UI flips back to login. AddExpenseForm → onAdded() → re-fetch → the list re-renders. Once I saw the one shape, the whole component tree stopped being mysterious.

Stuff I want to remember [the honest takeaways]

A JWT expiring is the security feature working, not a bug — but not handling the resulting 401 is the bug. Detect it and force a clean re-login.
Reproduce a time-based bug on purpose — corrupt the token in DevTools instead of waiting 30 minutes. An invalid token gives the same 401 as an expired one.
Check the specific status [401] before the generic !response.ok branch, or the general case masks the special one. Specific before general.
Props are how a parent passes data — and functions — down; a child reports events up by calling a function the parent gave it. Data down, events up.
{ prop } in a component signature is object destructuring [by name]; useState's [value, setter] is array destructuring [by position]. Same idea, different brackets — and the prop name must match exactly.
Colocate state: each form owns its own state and its own API call; the parent stays thin and owns only what's shared [the token]. Lift up only the shared thing.
Prop-forwarding is normal — a prop can be handed down through several layers [App → ExpenseList → AddExpenseForm].
When you restructure, hunt the leftovers — moving JSX into a child left a duplicated <h1> behind in the parent. [Same lesson as Part 1's stray render. It keeps coming back.]
Don't cargo-cult a lint "fix." Obeying the exhaustive-deps warning naively [[fetchExpenses]] creates an infinite fetch loop, because the function is recreated every render. The empty [] was correct. A warning is not an error. [Real fix = useCallback; deferred.]
Tailwind v4 is nothing like the v3 tutorials — no config file, no content array, no @tailwind directives. Just the @tailwindcss/vite plugin + @import "tailwindcss";. Verify current docs for fast-moving tools.
Tailwind is utility-first: compose a look from tiny classes on className [still not class]. Long, repeated class strings are normal.
flex items-center justify-center centers; flex flex-col gap-* spaces stacked children [set spacing on the parent, not margins on each child]; focus:/hover: prefixes are Tailwind's pseudo-classes; max-w-* mx-auto is the centered column.
Use semantic <header>/<main> instead of <div> soup — free clarity and accessibility.
The one React loop: data down (props) → event up (callback) → setState → re-render. Everything I built is that shape.
Commit at every green checkpoint, subject + why. I committed after the 401 fix, after each extraction, and after the Tailwind install — small and often.

Next up: Phase 5, for real this time. The face now has a pulse [the session no longer dead-ends], its internals are organized [small components that each own their job], and it's wearing its first real clothes [a login card and a dashboard shell]. What's left is to finish dressing the expense list, and then give the app some actual expression: a dashboard with spending insights — totals, spend-by-category, month-over-month — turning "it works and it's tidy" into "I'd genuinely use this." The foundation's finally solid enough to build something interesting on top of. See you there.

PHASE 4 — The Face

Azhar Alvi — Sat, 01 Aug 2026 09:29:14 +0000

Scaffold a React app, log in through a real form, and do full CRUD without ever opening /docs again — then close the three gaps nobody builds: loading, empty, and error.

So by the end of Phase 3 my app had a memory [a database], a mouth [HTTP endpoints], and a lock on the door [auth]. It knew who you were and refused to show you anyone else's expenses. Genuinely satisfying. There was just one small, embarrassing detail: the only human who could actually use it was me, poking at /docs. My "app" was a Swagger page and a lot of faith. No screen, no login box, nothing a normal person could look at. It had everything except a face.

Phase 4 gives it one.

A confession before we start: I changed the plan

If you read the end of my Phase 3 write-up, I promised Phase 4 would be filtering, sorting, and pagination — making the backend list usable at scale. I changed my mind. I went with frontend.

My reasoning, honestly: I've been living in Python for four phases and I've never touched React. Building the UI now forces me to re-meet my own auth, tokens, CORS, and endpoints from the client's side of the wire — which is the best way to find out whether I actually understood them. The known cost, which I'm accepting on purpose: GET /expenses is still unbounded, so when pagination lands later I'll have to come back and revise this list UI. Flagged, accepted, moving on.

Let's call it PHASE 4 — The Face:

Scaffold a real React app with Vite
Write my first component and actually understand JSX
Build a login form that holds its own text [controlled inputs + useState]
Call the backend from the browser — and get mugged by CORS
Store the token, and reckon with where to store it
Fetch and render the expense list [useEffect]
Close the three gaps: loading, empty, error
Wire up add / delete / edit — full CRUD from the UI
Fix the bug that made login "do nothing until I refreshed"

First, the new world [everything here is different from the backend]

The backend runs on Python; you install libraries with pip and freeze them into requirements.txt. The frontend has an exact parallel universe, and learning the mapping made the whole thing click:

Node.js is the JavaScript runtime — the "Python interpreter" of the frontend. [I'm on v22.]
npm is Node's package manager — this is pip. [I'm on v11.]
package.json is requirements.txt's counterpart — except it updates itself automatically when you install. No manual freeze step over here. One less habit to remember on this side of the fence.
node_modules/ is venv/ — enormous, machine-specific, and it must never touch git.
Vite [French for "quick," said veet] is the tool that scaffolds the app and runs the hot-reloading dev server. It's the frontend's uvicorn --reload.

Two forks in the road, two flagged shortcuts:

Vite offered me TypeScript or plain JavaScript. I took plain JS. TypeScript is fantastic and production-common, but it's a second new language stacked on top of React, and one new language at a time is plenty. [TypeScript = "know this exists," not now.]
It also asked which linter — Oxlint or ESLint. [A linter is a spell-checker for code: it reads your code without running it and flags likely bugs and sloppy style.] I picked ESLint because it's the industry default — when I hit an error and google it, ESLint results are everywhere. Oxlint is newer and faster but less documented. [Oxlint = know this exists.]

npm create vite@latest frontend -- --template react
cd frontend
npm install
npm run dev

That last command lit up a starter page at http://localhost:5173 with a clicky "count is 0" button — which, I later learned, is useState doing its thing. My first commit of the phase was that untouched scaffold, on its own: a clean "React works" checkpoint I could always fall back to before I started breaking things.

Habit that carried over: before committing, I checked git wasn't about to swallow node_modules. Turns out Vite drops its own .gitignore inside frontend/ — and yes, git supports multiple .gitignore files, one per folder. I didn't take that on faith [never, with git]; I ran git check-ignore frontend/node_modules and it echoed the path back, which is git saying "yep, ignoring that." Verify, don't assume.

Step 1: My first component [JSX has three rules that bite]

A React component is deceptively simple: it's just a JavaScript function, with a Capitalized name, that returns markup. That markup is JSX — it looks like HTML but it's actually JavaScript wearing a costume. I overwrote Vite's demo App.jsx with my own [safe: it's boilerplate, and I'd just committed, so git checkout would bring it back instantly]:

function App() {
  return (
    <div>
      <h1>Smart Expense Manager</h1>
      <p>Frontend is alive.</p>
    </div>
  )
}

export default App

Three JSX rules that trip everyone, now filed away:

One single root element. You can't return two side-by-side tags; wrap them in a parent. [React will yell at you.]
className, not class — because class is a reserved word in JavaScript.
{ } to drop a JS value into markup — {2 + 2} renders 4.

export default App is what lets main.jsx do import App from './App.jsx' — the JS version of exposing a name so another module can import it. I saved the file, and the browser instantly swapped to my text without a refresh. That's hot reload, and it's addictive.

Step 2: A login form that holds its own text [useState]

My instinct was to store what the user types in a normal variable — let email = ''. Wrong, and here's the precise why: React only updates the screen when it re-renders, and a plain variable changing doesn't trigger one. The box would go stale.

The fix is useState, a hook — a special function that lets a component remember a value across re-renders and re-render when that value changes.

import { useState } from 'react'

function App() {
  const [email, setEmail] = useState('')
  const [password, setPassword] = useState('')

  function handleSubmit(event) {
    event.preventDefault()
    console.log('Logging in with:', email, password)
  }

  return (
    <div>
      <h1>Smart Expense Manager</h1>
      <form onSubmit={handleSubmit}>
        <input
          type="email"
          placeholder="Email"
          value={email}
          onChange={(event) => setEmail(event.target.value)}
        />
        <input
          type="password"
          placeholder="Password"
          value={password}
          onChange={(event) => setPassword(event.target.value)}
        />
        <button type="submit">Log in</button>
      </form>
    </div>
  )
}

New ideas, in plain language:

const [email, setEmail] = useState('') returns a pair — the current value and a setter. That [...] unpacking is array destructuring. The iron rule: never reassign email directly — always call setEmail(...). The setter is what tells React "this changed, re-render."
Controlled input — the two-way loop that is the React form pattern: value={email} makes the box always display state, onChange pushes every keystroke back into state. State is the single source of truth; the input just mirrors it.
import { useState } with braces is a named import; import App without braces is a default import. The braces are the tell.

And the one that will get me someday:

Gotcha #1 — event.preventDefault() is not optional. By default, submitting an HTML form makes the browser reload the entire page [a genuine 1990s behavior]. In a React app that wipes all your state and blanks the screen. preventDefault() cancels it so I stay in control. I know for a fact I'll forget this line one day and watch my page flash — but now I'll know exactly why.

I opened DevTools, typed in both boxes [text appeared as I typed — the loop works], clicked Log in, and watched Logging in with: ... print to the console with no page reload. First real interaction, done.

Step 3: Call the backend — and get mugged by CORS

Now the browser had to actually talk to FastAPI. Two new concepts collided here.

First, async / await and fetch. Network calls take time, and JavaScript can't freeze the browser waiting. So fetch [the browser's built-in HTTP client — the JS version of Python's requests] returns a Promise, an "I'll have your answer later" placeholder. await pauses this function until it resolves, and any function using await must be marked async [same word as FastAPI's async def].

Second — and this is the single biggest gotcha of the whole phase:

Gotcha #2 — the login endpoint is the odd one out: it wants FORM data, not JSON. My /auth/login uses OAuth2PasswordRequestForm, which reads application/x-www-form-urlencoded, not JSON. Send it JSON and you get a baffling 422. So I built the body with URLSearchParams and set the matching Content-Type. Bank this: the OAuth2 login endpoint is form-encoded; every other endpoint in my API speaks JSON. Mixing these two up is the classic source of 422s.

async function handleSubmit(event) {
  event.preventDefault()
  const formBody = new URLSearchParams()
  formBody.append('username', email)   // OAuth2 calls the field "username" — I put my email there
  formBody.append('password', password)

  const response = await fetch('http://localhost:8000/auth/login', {
    method: 'POST',
    headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
    body: formBody,
  })
  const data = await response.json()
  console.log('Status:', response.status, 'Body:', data)
}

My mentor predicted this would fail, and it did — with a big red wall:

Gotcha #3 — CORS, the thing my roadmap warned trips up everyone. Access to fetch at 'http://localhost:8000/auth/login' from origin 'http://localhost:5173' has been blocked by CORS policy: No 'Access-Control-Allow-Origin' header... My frontend runs on port 5173, my backend on 8000 — different port means the browser considers them different origins, and it refused to let my code read the response.

CORS [Cross-Origin Resource Sharing] is a browser security feature, not a bug in my code. The scenario it prevents: you're logged into your bank in one tab, you visit a sketchy site in another, and that site's JavaScript quietly fires requests at your bank using your session. To stop that, the browser won't let JS on origin A read a response from origin B unless server B explicitly says it allows A. Server B says so with an Access-Control-Allow-Origin header — which my FastAPI wasn't sending. Getting the error actually meant my request was leaving the browser correctly; the backend just hadn't granted permission yet.

The fix lives on the backend, via FastAPI's CORSMiddleware [a middleware is code that wraps every request/response — perfect for stamping a header onto everything]. Bonus: it ships inside FastAPI, so no install, no requirements.txt change this time.

from fastapi.middleware.cors import CORSMiddleware

app.add_middleware(
    CORSMiddleware,
    allow_origins=["http://localhost:5173"],  # the whitelist — explicit, never "*"
    allow_credentials=True,
    allow_methods=["*"],
    allow_headers=["*"],
)

Two decisions worth stating:

Never allow_origins=["*"]. It defeats the point, and the browser flat-out forbids "*" together with allow_credentials=True. Always list explicit origins. [Flagged shortcut: I hardcoded the dev URL. Production reads allowed origins from an env var and lists the real Vercel domain — that's my Phase 9 deploy task.]
allow_headers=["*"] matters because I'm about to start sending an Authorization header on every protected request.

uvicorn hot-reloaded, I clicked Log in again, and the CORS error was gone — replaced by a clean 401, because my dev database was freshly regenerated and had zero users. A 401 round-trip was a success: the browser-to-backend pipe now worked end to end. I registered a test user through /docs, typed the same credentials into my form, and got 200 with a glorious { access_token: "eyJ...", token_type: "bearer" }. My React app had fetched its own JWT.

Step 4: Store the token [the one real security decision this phase]

The token vanished the instant handleSubmit finished. I needed to keep it — every future request has to attach it, and a refresh shouldn't log me out. Enter localStorage: a tiny per-origin key-value store built into the browser, persists across reloads, dead-simple API [setItem, getItem, removeItem], values are always strings.

if (response.ok) {
  const data = await response.json()
  localStorage.setItem('token', data.access_token)
}

[response.ok is a boolean that's true for any 2xx — the clean way to ask "did this succeed?" instead of eyeballing status numbers.]

Here's where I put the security hat back on, because it genuinely matters:

localStorage is readable by any JavaScript running on my page. So if an attacker ever injects a script into my app — that's an XSS [cross-site scripting] attack — they can read the token straight out of storage and impersonate the user. That's the real risk, stated plainly.

What I did [flagged learning shortcut]: store the JWT in localStorage. Simple, easy to inspect while learning, sidesteps cookie/CORS-credential complexity.
What production does: store it in an httpOnly, Secure, SameSite cookie. httpOnly means JavaScript literally cannot read it, so even a successful XSS can't steal it, and the browser attaches it automatically. [Know this exists. Not building it now.]

React's own defense is worth knowing too: it auto-escapes any text you render, which neutralizes most XSS by default. The danger zone is a prop literally named dangerouslySetInnerHTML — the scary name is the warning. Don't use it and you dodge the common trap.

I logged in, opened DevTools → Application → Local Storage, saw my token key sitting there, refreshed the page, and it survived. That persistence is the whole point.

Step 5: The expense list [useEffect, and the infinite-loop trap]

Reading data needs useEffect, and I'm glad I learned the trap before hitting it. A component function re-runs on every render. So you can't just drop a fetch in the component body — it'd fire on every render, hammer the API, and [if it sets state] spin into an infinite re-render loop.

useEffect lets you say "run this as a side effect, but only at specific times." The dependency array [second argument] controls when:

[] empty → run once, right after the component first mounts. Exactly what "fetch when the page loads" wants.
[x] → also re-run when x changes.
omitted entirely → run after every render. The infinite-loop trap. Don't.

One quirk: the effect function itself can't be async, so the pattern is to define an async function inside it and call it immediately.

import { useState, useEffect } from 'react'

function ExpenseList() {
  const [expenses, setExpenses] = useState([])

  useEffect(() => {
    async function fetchExpenses() {
      const token = localStorage.getItem('token')
      const response = await fetch('http://localhost:8000/expenses', {
        headers: { Authorization: `Bearer ${token}` },
      })
      const data = await response.json()
      setExpenses(data)
    }
    fetchExpenses()
  }, [])
  // ...
}

That `Bearer ${token}` is a template literal — backticks let you embed a variable with ${...}. It produces the exact string my /docs "Authorize" button sends, which is how the app proves who it is on every protected request. The fetch came back with a clean empty array [] — correct, since my test user had no expenses yet. Authentication working from the client side, first time.

Step 6: The three gaps nobody builds [loading, empty, error]

This is the heart of the phase. And it starts with a gotcha that burns everyone:

Gotcha #4 — fetch does NOT throw on a 404 or 500. It only rejects when the network itself fails [server down, CORS block]. A 401 or 500 is, to fetch, a perfectly "successful" round-trip that happens to carry a bad status. So you have to check response.ok yourself and deliberately throw on a bad status. Coming from Python's requests, this genuinely surprised me.

I handled both failure kinds with try / catch / finally [same shape as Python]. finally runs no matter what — the perfect home for setLoading(false), so a loading spinner can never get stuck on screen. And I rendered the states with early returns in strict priority order: loading → error → empty → list.

const [expenses, setExpenses] = useState([])
const [loading, setLoading] = useState(true)
const [error, setError] = useState(null)

useEffect(() => {
  async function fetchExpenses() {
    const token = localStorage.getItem('token')
    try {
      const response = await fetch('http://localhost:8000/expenses', {
        headers: { Authorization: `Bearer ${token}` },
      })
      if (!response.ok) {
        throw new Error(`Request failed: ${response.status}`)
      }
      const data = await response.json()
      setExpenses(data)
    } catch (err) {
      setError('Could not load expenses. Please try again.')
      console.error(err)
    } finally {
      setLoading(false)
    }
  }
  fetchExpenses()
}, [])

The part tutorials skip — I tested the error gap on purpose. I hit Ctrl+C on the backend, refreshed the browser, and instead of a blank frozen page I got my red "Could not load expenses. Please try again." That's the adversarial habit surviving even without the GAN framing: don't just build the happy path, actively try to break it.

Then rendering the list with .map() — the array method that turns each expense object into an <li>. Every mapped element needs a key — a stable unique id so React can track rows across re-renders. Use the database id, never the array index [index breaks the moment the list reorders or an item is removed].

While wiring this, a small honest scope decision surfaced: my mentor's example row showed a category field. My Expense model doesn't have one. Adding it isn't a display tweak — it's a new column, a migration, and schema changes. That's literally what my roadmap's Phase 7 [AI categorization] is for. So I dropped it rather than scope-creep a clean foundation phase. [category → deferred to Phase 7.] My real ExpenseRead returns id, amount, description, spent_on, and timestamps — and a nice detail: because amount is a Decimal, Pydantic serializes it to a string on purpose, to protect money from float rounding.

Step 7: Full CRUD from the UI [add, delete, edit]

Add [POST]. Same JSON pattern I'll use everywhere except login: Content-Type: application/json and body: JSON.stringify({...}). On success, I clear the form and re-fetch the list so the new row appears — letting the server stay the single source of truth. To make that re-fetch reusable, I pulled fetchExpenses out of useEffect into the component body, so both the initial load and every post-write refresh could call it.

async function handleAdd(event) {
  event.preventDefault()
  const token = localStorage.getItem('token')
  const response = await fetch('http://localhost:8000/expenses', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      Authorization: `Bearer ${token}`,
    },
    body: JSON.stringify({ description, amount, spent_on: spentOn }),
  })
  if (response.ok) {
    setDescription(''); setAmount(''); setSpentOn('')
    fetchExpenses()
  }
}

[A lovely bit of luck: an <input type="date"> gives a date-picker whose value is already a "YYYY-MM-DD" string — exactly what my Python date field wants, zero conversion.]

Adding the always-visible form forced a rendering upgrade. Early returns worked when the whole component was one state, but the form has to show even in the empty state. So I switched to inline conditional rendering with &&:

{loading && <p>Loading expenses…</p>}
{error && <p style={{ color: 'red' }}>{error}</p>}
{!loading && !error && expenses.length === 0 && <p>No expenses yet.</p>}
{!loading && !error && expenses.length > 0 && ( /* the list */ )}

The lesson worth banking: early-return when the entire component is one state; inline && when only part of the UI changes.

Gotcha #5 — one missing ! showed two contradictory states at once. For a while my app displayed "Could not load expenses" and "No expenses yet" simultaneously — which is impossible; those are supposed to be mutually exclusive. The cause was hilariously small: my empty-state guard was missing the !error check. One character [!] fixed it. A whole render bug lived in a single missing symbol.

Delete [DELETE]. Two things I hadn't met:

Gotcha #6 — a 204 has no body, so don't parse one. My DELETE returns 204 No Content — by definition, empty. Calling response.json() on it would throw. Just check response.ok and move on.

Gotcha #7 — passing an argument to a handler needs an arrow wrapper. To delete a specific row I wrote onClick={() => handleDelete(expense.id)}. If I'd written onClick={handleDelete(expense.id)} [no arrow], React would call it immediately during render — deleting everything the instant the list appeared. The arrow hands React a function to call later, on click. Rule of thumb I locked in: no args → pass the reference [onClick={handleLogout}]; need args → wrap in an arrow.

Edit [PATCH]. The biggest UI concept: per-row edit mode. I track which row is editing with a single editingId [null = nobody], and render with a ternary — "if this row is being edited, show inputs; otherwise show text + buttons." Each branch has to return one element, so I wrapped the siblings in a Fragment [<>...</>] — an invisible grouping tag that adds no extra <div> to the page.

PATCH is a partial update: my backend's ExpenseUpdate has all-optional fields, and it saves with payload.model_dump(exclude_unset=True) → setattr → db.commit() → db.refresh(). On success I close edit mode and re-fetch, same source-of-truth habit.

With edit working, I'd hit the phase's finish line: log in through the UI and do full create/read/update/delete without ever opening /docs.

Step 8: The bug that made login "do nothing until I refreshed"

This one deserves its own section because it taught me the deepest React lesson of the phase. My symptom: I'd log in, and nothing happened — until I refreshed the page, at which point it worked perfectly.

The cause, once I understood it, is fundamental:

Gotcha #8 — React does not watch localStorage. My login handler wrote the token to localStorage, but React only re-renders when a piece of state changes. Writing to storage is completely invisible to it. And my ExpenseList fetched only once, on mount — so on a fresh load it fired with Bearer null, failed, and never ran again. Logging in stashed a token, but nothing told React anything had changed. A refresh "fixed" it only because it re-mounted the whole app after the token was already in storage.

The fix was my first taste of lifting state up: the token belongs in App [the parent], because App is what decides between "logged out" and "logged in." I put the token in React state, seeded from storage, and set it on login:

const [token, setToken] = useState(localStorage.getItem('token'))  // survives refresh

// in the login success branch:
localStorage.setItem('token', data.access_token)
setToken(data.access_token)  // <-- THE missing trigger. State change → re-render → instant switch.

// gate the whole UI on it:
if (token) {
  return (
    <div>
      <h1>Smart Expense Manager</h1>
      <button onClick={handleLogout}>Log out</button>
      <ExpenseList />
    </div>
  )
}
// otherwise fall through to the login form

Logout is just login run backwards — clear both copies of the token:

function handleLogout() {
  localStorage.removeItem('token')  // so a refresh won't silently log me back in
  setToken(null)                    // so the gate falls through to the login form
}

Two more real bugs fell out of this, and both are honest lessons:

The stray-render leak. After adding the gated view, logging out still showed the expense list — because an earlier <ExpenseList /> was still sitting in the logged-out return from a previous step. I'd added the new one without removing the old. ExpenseList should appear in exactly one place. A quick file search [it should show up twice: the import + one render] caught it. Lesson: when you restructure, hunt down the leftovers.
Incognito confused me for a minute. Logged in on a normal window, I opened incognito, logged in there, and the two windows behaved independently. That's correct — localStorage is isolated per browser profile, so incognito has its own separate store. [Imagine if it didn't; that'd be a leak.] Two normal tabs share storage but not live React state, so one won't visually update until it refreshes. [Live cross-tab sync via the storage event = know this exists.]

Bonus: so how does clicking "Save" actually change the database?

This confused me, so I'll write down the model that fixed it: there are three separate programs, and none can touch the others' memory.

My React app — JavaScript in the browser. It knows nothing about the database. All it can do is send HTTP requests.
My FastAPI backend — Python in the uvicorn terminal. The only program that talks to the database.
SQLite — the expenses.db file. It only ever hears from the backend.

So the Save button does not save to the database. It sends a PATCH note to the backend asking it to save. The backend checks my token, finds my row [scoped to my user id — my Phase 3 ownership filter riding along], sets the new values, and runs db.commit() — that single line is the actual write to disk. Then it replies 200, and my browser re-fetches so the screen matches what the database now says. Every operation in the app is that same shape: Create = POST + commit, Delete = DELETE + commit, Update = PATCH + commit, Read = GET [no commit — nothing changes]. Once that one round-trip clicked, the whole app made sense.

Stuff I want to remember [the honest takeaways]

The frontend has an exact mirror of the backend's tools: Node = Python, npm = pip, package.json = requirements.txt [but it auto-freezes], node_modules = venv, Vite = uvicorn.
A component is a Capitalized function returning JSX. JSX rules that bite: one root element, className not class, { } for JS values.
useState returns a [value, setter] pair. Never reassign the value — always call the setter. The setter is the only thing that triggers a re-render.
React only re-renders on state change. It does not watch localStorage. This one fact caused my nastiest bug.
Controlled inputs [value + onChange] make state the single source of truth for a form.
event.preventDefault() stops the browser's default full-page reload on form submit. You will forget this once.
CORS is a browser security feature, not a bug in your code. Different port = different origin; the fix is CORSMiddleware on the backend, with an explicit origin whitelist [never "*" with credentials].
The OAuth2 login endpoint is the odd one out — it wants form-encoded data. Everything else speaks JSON. Mixing them up is the classic 422.
fetch does NOT throw on 4xx/5xx. Check response.ok yourself and throw deliberately. Use try/catch/finally, and put setLoading(false) in finally so it can never get stuck.
Build the happy path, then close the three gaps: loading, empty, error — and actually test the error state by killing the backend.
.map() renders lists; every item needs a stable key — use the DB id, never the array index.
&& for show-or-nothing; ternary ? : for A-or-B; Fragments <>...</> to group siblings without an extra <div>.
Passing args to a handler needs an arrow wrapper [() => fn(id)] or it fires during render. No args → pass the reference.
A 204 response has no body — don't call .json() on it.
JWT in localStorage is a flagged shortcut [readable by any JS → XSS risk]. Production uses an httpOnly Secure SameSite cookie. React auto-escapes text; avoid dangerouslySetInnerHTML.
The Save button doesn't save — it asks the backend to. db.commit() is the real write. The browser, the backend, and the database are three separate programs passing notes.
When you restructure, hunt the leftovers — a stray render leaked my list into the logged-out view.
Commit at every green checkpoint, with a subject + a "why." Small and often beats one heroic commit.

Next up: Phase 5. The app now has a memory, a mouth, a lock, and — finally — a face a human can log into and use. But that face is honest to a fault: it's a raw list with no styling, no summaries, and a login that just... stops working after 30 minutes with a confusing error [my JWTs expire, and I don't handle it yet]. Phase 5 is where the face gets some expression — a dashboard, spending insights, and the polish that turns "it works" into "I'd actually use this." That, and I owe this app an "expired-token → send me back to login" fix I flagged and walked away from. See you there.

Teaching My Backend to Lock the Door — FastAPI Auth, Phase 3

Azhar Alvi — Sat, 25 Jul 2026 09:06:27 +0000

Hash the password, hand out a token, and make absolutely sure no one can read someone else's expenses.

So Phase 2 gave my app a mouth. It could finally talk — create, read, update, and delete expenses over real HTTP endpoints, all clicking together through /docs. But there was a giant, deliberately-ignored problem sitting in the middle of it: the door had no lock. Anyone who could reach the server could read, edit, or delete anything. And every expense I created was quietly stamped with the same hardcoded owner — a "dev user" whose id I'd nailed into the code with a # TEMP note and a promise to fix it "in Phase 3."

Well. It's Phase 3. Time to pay that debt.

This is where the app grows a bouncer. The buzzword is auth, which actually hides two jobs that sound the same and aren't: authentication ["who are you?"] and authorization ["okay, but are you allowed to touch this?"]. I went in thinking auth was "add a login form" and came out having learned about one-way hashing, signed tokens, a security bug with the excellent name IDOR, and why the same password can produce two different hashes. Let me dump what I learned [and the parts that tripped me up, because — as usual — there were several].

Auth is the one phase where you have to stop thinking like a builder and start thinking like the person trying to rob you. So every step below is really "here's a way an attacker wins, and here's the gap I closed to stop them."

The structure. Let's call it PHASE 3 — The Lock:

Give the User table somewhere to store a password [a hashed one, never the real thing]
Password hashing helpers — turn a password into something safe to store
POST /auth/register — sign up with a hashed password
Understand what a JWT actually is [it's just a signed string, and it's readable]
POST /auth/login — check the password, hand back a token
get_current_user — the gatekeeper that turns a token back into a user
Lock every expense endpoint and scope it to the logged-in owner
Retire the hardcoded DEV_USER_ID for good
Prove two users can't see each other's data

First, the new ideas [and yes, this time there IS stuff to install]

Unlike Phase 2, this phase actually adds libraries — so the pip freeze habit is back on. Three new tools, in plain language:

passlib [with bcrypt] — the password shredder. bcrypt is the actual algorithm; passlib is the friendly wrapper around it. Its whole job is to turn a password into a hash — a scrambled string you can store safely — using a method that's deliberately slow and salted [more on both of those below].
PyJWT — the token machine. It creates and verifies JWTs, the signed strings that let a user prove "I'm logged in" on every request without re-sending their password. [Gotcha you'll hit: you pip install pyjwt but you import jwt. The names don't match. File that away now.]
python-multipart — an unglamorous helper that lets FastAPI read form data, which the standard login flow uses. You don't call it directly; FastAPI just needs it present.

pip install "passlib[bcrypt]" pyjwt python-multipart
pip freeze > requirements.txt

The quotes around "passlib[bcrypt]" matter — the brackets tell pip to pull bcrypt in as an extra. And the moment you install something, freeze it, so the next machine [including future-you] rebuilds the identical environment.

Step 1: Give users a place to store a password [a hashed one]

Here's the rule that governs this entire phase, and it's worth tattooing somewhere: you never store the password. You store a one-way hash of it.

My User model from Phase 1 had name, email, and timestamps — but no password field at all, because I built it before auth existed. So it needs one new column:

hashed_password: Mapped[str] = mapped_column(String, nullable=False)

Two deliberate choices:

It's called hashed_password, not password. The name is a permanent reminder to everyone [me, in three weeks] that this field holds a hash, never plaintext. If you ever spot raw text in there, something is badly broken.
It's not unique and not indexed [unlike email]. You never look a user up by their hash — you find them by email, then verify the hash in code. Indexing it would be wasted effort.

A new column means a new migration. Same autogenerate → review → apply rhythm from Phase 1:

alembic revision --autogenerate -m "add hashed_password to users"

I reviewed the generated file [op.add_column(... nullable=False)] and then hit the wrinkle that became my first real lesson this phase.

Gotcha #1 — the NOT NULL wall. SQLite refuses to add a NOT NULL column to a table that already has rows, because those existing rows have no value for it. My table had that old seeded dev user in it. Two honest paths: the production way [add the column nullable, backfill every row, then a second migration to flip it to NOT NULL — zero data loss], or the learning way [my only data was throwaway, so wipe it and rebuild]. My mentor made me say out loud that we were taking a shortcut. I took it — but now I know the real move for when the data actually matters.

⚠️ Destructive-command warning [the first of this phase]: rebuilding from scratch deletes every local row. Safe here only because it's junk dev data. Rather than delete the .db file by hand, I stayed inside Alembic — which also proves my whole migration chain works end to end:

alembic downgrade base   # drops everything back to empty [the destructive line]
alembic upgrade head     # replays all migrations onto empty tables

Step 2: The hashing helpers [hashing is NOT encryption]

Before I could register anyone, I needed two tiny functions: one to hash a password on the way in, one to verify a login attempt later. Best practice says security code lives in its own file, so this is a new security.py:

from passlib.context import CryptContext

pwd_context = CryptContext(schemes=["bcrypt"], deprecated="auto")


def hash_password(password: str) -> str:
    return pwd_context.hash(password)


def verify_password(plain_password: str, hashed_password: str) -> bool:
    return pwd_context.verify(plain_password, hashed_password)

The single most important concept here — and it took a beat to click:

Hashing is one-way. Encryption is two-way. You can encrypt something and later decrypt it back. You can hash a password, but you can never turn the hash back into the password. That's the entire point: even I, running the server, can't see anyone's password. If my whole database gets stolen, the attacker gets a pile of useless $2b$... strings, not passwords. That's the first gap closed.
bcrypt is deliberately slow. Sounds like a bug; it's a feature. Slowness makes brute-forcing millions of guesses painfully expensive for an attacker while costing a real login a few harmless milliseconds.
bcrypt auto-salts. It mixes a random value into every hash, so two people with the same password get different hashes. That kills "rainbow table" attacks [precomputed hash lookups]. I proved this to myself: hashing "supersecret123" twice gave two totally different strings. Same input, different output — the salt, visibly doing its job.
deprecated="auto" is the sneaky-clever bit. Because every hash records which algorithm made it [the $2b$ prefix is bcrypt's ID card], I can add a newer algorithm years from now and passlib will keep verifying old hashes and silently upgrade them the next time each user logs in. Nobody gets locked out, nobody resets their password. Algorithm agility, for one word of config.

I tested it in a plain python shell: hash_password("supersecret123") gave a long $2b$... string, verify_password("supersecret123", h) returned True, and verify_password("wrong", h) returned False. Then the version gods showed up.

Gotcha #2 — the 72-byte error on a 14-character password. My first real hash blew up with ValueError: password cannot be longer than 72 bytes. My password was 14 characters. What?! The culprit: passlib 1.7.4 is old and unmaintained, and modern bcrypt [4.1+] changed an interface it relies on. On its first run, passlib runs an internal self-test that trips the new bcrypt's 72-byte guard — before my password is ever touched. The fix was to pin bcrypt to the last version passlib understands:
pip install "bcrypt==4.0.1"
pip freeze > requirements.txt
This was also the moment "why do we freeze?" stopped being abstract — without the pin, a fresh install would grab the broken-for-me newest bcrypt all over again. [The modern alternative is a library called pwdlib; passlib is on its way out. Noted for a future refactor.]

Step 3: POST /auth/register [where the hash finally gets used]

Two schemas, exactly like Phase 2's input/output split — but with one security rule bolted on. In schemas.py:

class UserCreate(BaseModel):
    """What a client sends to register."""
    name: str = Field(min_length=1, max_length=100)
    email: str
    password: str = Field(min_length=8)


class UserRead(BaseModel):
    """What the server sends back — no password, no hash, EVER."""
    id: int
    name: str
    email: str
    created_at: datetime

    model_config = ConfigDict(from_attributes=True)

Look at what UserRead is missing: the password and the hash. This is a real gap — if the stored hash ever showed up in an API response, an attacker who can read responses gets a head start on cracking it. Leaving it out of the output schema makes that leak structurally impossible. Same trick as response_model=ExpenseRead in Phase 2, now doing security work.

The endpoint, in main.py:

@app.post("/auth/register", response_model=UserRead, status_code=status.HTTP_201_CREATED)
def register(payload: UserCreate, db: Session = Depends(get_db)):
    existing = db.scalars(select(User).where(User.email == payload.email)).first()
    if existing is not None:
        raise HTTPException(status_code=409, detail="Email already registered")

    user = User(
        name=payload.name,
        email=payload.email,
        hashed_password=hash_password(payload.password),
    )
    db.add(user)
    db.commit()
    db.refresh(user)
    return user

hashed_password=hash_password(payload.password) is the one line that makes this safe. The plaintext exists only long enough to be hashed, right here, and is never stored. What lands in the database is the $2b$... string.
The /auth/ prefix namespaces auth routes together — tidy as the API grows. [The neater-still version is a separate APIRouter file; leaving that for later so I'm not juggling files mid-concept.]
409 Conflict is the precise code for "your request is fine, but it clashes with something that already exists" — here, a taken email. More specific than a generic 400. [The fully robust version wraps the insert in a try/except IntegrityError to close a tiny race where two people register the same email at the same instant; the DB's unique constraint still protects integrity either way. Noted, not built.]

Tested through /docs: register → 201, and the response showed id, name, email, created_at and — crucially — no hashed_password. Registering the same email again → 409.

Step 4: What a JWT actually is [read this before you trust one]

This was the concept I most needed to get before writing more code. A JWT [JSON Web Token, said "jot"] is just a signed string the server hands you at login. You send it back on every future request, and it proves "I'm logged in" — without the server having to remember sessions. The token itself carries the proof.

It has three parts separated by dots: header.payload.signature.

Header — which signing algorithm was used [I used HS256].
Payload — the "claims," i.e. the data. I put in sub [subject — who the token is about; I store the user's id] and exp [expiry].
Signature — the header and payload, signed with my secret key.

Here's the thing that reframed everything for me: the payload is only base64-encoded, not encrypted. Anyone who grabs the token can read it — paste one into jwt.io and you'll see the user id in plain text. So the rule is: never put anything secret in a JWT. What a token buys you isn't secrecy — it's integrity. Change one character of the payload [say, to a different user's id] and the signature no longer matches, so the server rejects it. An attacker can't forge a valid signature because only my server knows the secret key.

Which is exactly why that key can never leak. If someone learns my SECRET_KEY, they can mint valid tokens for any user — a total bypass. So it lives in .env [already gitignored since Phase 0], generated with real randomness:

python -c "import secrets; print(secrets.token_hex(32))"

SECRET_KEY=that_64_char_hex_value
ACCESS_TOKEN_EXPIRE_MINUTES=30

That 30-minute expiry closes another gap: a stolen token stops working within half an hour instead of forever. [Real apps pair a short access token with a longer "refresh token" so users aren't logged out constantly. Not building refresh tokens this phase — that'd be over-engineering right now.]

Then I wrote the token minter in security.py:

def create_access_token(subject: str) -> str:
    expire = datetime.now(timezone.utc) + timedelta(minutes=ACCESS_TOKEN_EXPIRE_MINUTES)
    payload = {"sub": subject, "exp": expire}
    return jwt.encode(payload, SECRET_KEY, algorithm=ALGORITHM)

Note the timezone-aware UTC expiry — same discipline as Phase 1's timezone=True columns. Auth timestamps must be unambiguous across servers.

Gotcha #3 — the misspelled keyword that wasn't a version bug. Setting up CryptContext earlier, I hit KeyError: unknown CryptContext keyword. I assumed another bcrypt version mess. But my mentor made me read the traceback bottom-up first — and the last line said it plainly: an argument I passed doesn't exist. I'd typed depreciated [the accounting word, with an i] instead of deprecated. Case-and-spelling-sensitive libraries do not forgive. Reading the traceback saved me from "fixing" something that was never broken.

Gotcha #4 — a .env file does nothing on its own. My SECRET_KEY = os.environ["SECRET_KEY"] crashed with a KeyError. Turns out I'd been reading env vars with os.getenv all along but never actually loading the .env file into the environment — my DATABASE_URL only "worked" because it had a default fallback that quietly kicked in. A .env file is just text; something has to copy it into the environment first. That something is load_dotenv():
from dotenv import load_dotenv
load_dotenv()   # must run BEFORE anything reads a variable
Lesson that stuck: loading and reading are two different jobs. load_dotenv() loads; os.getenv() reads. And my strict, no-fallback SECRET_KEY line is what exposed the gap the fallback had been hiding — fail-fast earning its keep.

Step 5: POST /auth/login [check the password, hand back a token]

This is where hashing and JWTs meet. I built login the standard FastAPI way, with OAuth2PasswordRequestForm — which, bonus, lights up the green Authorize button in /docs.

@app.post("/auth/login", response_model=Token)
def login(
    form_data: OAuth2PasswordRequestForm = Depends(),
    db: Session = Depends(get_db),
):
    user = db.scalars(select(User).where(User.email == form_data.username)).first()
    if user is None or not verify_password(form_data.password, user.hashed_password):
        raise HTTPException(
            status_code=401,
            detail="Incorrect email or password",
            headers={"WWW-Authenticate": "Bearer"},
        )
    access_token = create_access_token(subject=str(user.id))
    return {"access_token": access_token, "token_type": "bearer"}

The quirk everyone hits: the OAuth2 spec calls the field username, but I put the email there. So at login you type your email into the box labeled "username." Normal in FastAPI land.
The vague error is on purpose. Whether the email doesn't exist or the password is wrong, I return the exact same 401 with the same message. If I distinguished them, an attacker could probe which emails are registered — a leak called user enumeration. One generic message, closed. Do this now, it's free.
subject=str(user.id) stamps the user's id into the token's sub claim. That breadcrumb is the whole point — it's how the next step figures out who a request is from, with no password involved.

The docs also show grant_type, scope, client_id, client_secret fields — all part of the full OAuth2 spec, all safely ignorable for my app. Only username and password matter here.

Tested: right email + password → 200 with a token; wrong password → 401. And it taught me a bit of Python grammar I'd been fuzzy on — : describes [amount: Decimal, a dict pair {"key": "value"}, the : that opens a block] while = assigns [x = 5, or a keyword arg status_code=401]. Same word can flip: subject: str in a definition vs subject=... in a call.

Step 6: get_current_user [the gatekeeper]

This is the piece every locked endpoint leans on. It turns a token back into a real, live user — the concrete form of authentication. First a decode helper in security.py:

def decode_access_token(token: str) -> dict:
    return jwt.decode(token, SECRET_KEY, algorithms=[ALGORITHM])

jwt.decode does two jobs at once: verifies the signature [proving I minted it, untampered] and checks the exp [rejecting expired tokens]. Either failure raises. Then the dependency in main.py:

oauth2_scheme = OAuth2PasswordBearer(tokenUrl="auth/login")


def get_current_user(
    token: str = Depends(oauth2_scheme),
    db: Session = Depends(get_db),
) -> User:
    credentials_exception = HTTPException(
        status_code=401,
        detail="Could not validate credentials",
        headers={"WWW-Authenticate": "Bearer"},
    )
    try:
        payload = decode_access_token(token)
        user_id = payload.get("sub")
        if user_id is None:
            raise credentials_exception
    except jwt.InvalidTokenError:
        raise credentials_exception

    user = db.get(User, int(user_id))
    if user is None:
        raise credentials_exception
    return user

OAuth2PasswordBearer automatically pulls the token out of the incoming Authorization: Bearer <token> header [401 if it's missing] and is what finally enables the Authorize button.
One except jwt.InvalidTokenError covers a bad signature, a malformed token, and an expired one [expiry raises a subclass], all funnelling to the same generic 401. No-leak discipline again.
db.get(User, ...) fetches the actual user rather than blindly trusting the token — so a deleted user's leftover token stops working. Returning the User object is the magic: any endpoint that depends on this gets the logged-in user handed straight to it.

I proved it with a throwaway GET /auth/me that just returns current_user: authorized → 200 with my user; no token → 401.

Gotcha #5 — case-sensitivity, twice. First Oauth2PasswordBearer is not defined, then again — because "OAuth" is an acronym and both the O and the A are uppercase: OAuth2PasswordBearer. I'd lowercased the A. Python doesn't care that it's "obviously" the same word.

Gotcha #6 — order matters for dependencies. I also hit get_current_user is not defined on an endpoint. Not a typo this time — an ordering problem. Python evaluates Depends(get_current_user) in the function's default arguments the moment it reads the def line, so get_current_user has to be defined above any endpoint that uses it. Moved the gatekeeper up near the top of main.py, above the routes. [Same reason get_db has always worked — defined before its consumers.]

Step 7: Lock the endpoints and scope them to the owner [the boss fight]

This is what the whole phase was building toward — and it's the real difference between authentication [we know who you are] and authorization [you may only touch your own rows]. Every expense endpoint gets the same two changes: add current_user: User = Depends(get_current_user), then use current_user.id — for writes, stamp it; for reads, filter by it.

Create finally retires the shortcut:

expense = Expense(**payload.model_dump(), user_id=current_user.id)   # was DEV_USER_ID

And the isolation-critical read — fetch by id AND owner:

@app.get("/expenses/{expense_id}", response_model=ExpenseRead)
def get_one_expense(
    expense_id: int,
    db: Session = Depends(get_db),
    current_user: User = Depends(get_current_user),
):
    expense = db.scalars(
        select(Expense).where(
            Expense.id == expense_id,
            Expense.user_id == current_user.id,
        )
    ).first()
    if expense is None:
        raise HTTPException(status_code=404, detail="Expense not found")
    return expense

That double .where(...) closes the scariest gap in the phase — IDOR [Insecure Direct Object Reference]: the bug where a logged-in User A simply asks for User B's expense by its id. Because the query filters on user_id too, A's request for B's row returns nothing → a clean 404. The ownership check lives in the query itself, so I literally cannot forget it later. The list, PATCH, and DELETE endpoints all got the same treatment [filter the list by owner; fetch-scoped-by-owner before updating or deleting], so it's impossible to even load someone else's row to change it.

Two small but real decisions:

404, not 403, when the row isn't yours. Saying 403 ["that exists, but you can't have it"] would leak that the id exists. 404 reveals nothing. Same no-leak instinct as the login error.
db.scalars(...) + .first() / .all() — db.scalars() hands me clean model objects [not row-tuples], .first() gives one object or None [get-one], .all() gives a list [the list endpoint]. Different endings for different needs.

Then the symbolic finish line — deleting the hardcoded owner. But not before checking it's actually unused:

grep -rn "DEV_USER_ID" .

Habit worth keeping: grep-before-delete. It turns "I think it's unused" into "I've confirmed it's unused." Only the definition line showed up, so I deleted it. DEV_USER_ID is officially retired — 3 phases after I promised it would be.

Step 8: Prove it [the part tutorials skip]

Writing auth code isn't the same as verifying auth works. So I put on the attacker hat and ran the isolation proof my roadmap demanded, entirely through /docs:

Registered a second user, Bob.
As User A: created an expense [id 1], confirmed GET /expenses showed only mine.
Logged out, authorized as Bob — the attacker:
- GET /expenses → empty list []. Bob has nothing. [If A's expense showed up here, isolation was broken.]
- GET /expenses/1, PATCH /expenses/1, DELETE /expenses/1 → 404, 404, 404. Bob can't read, edit, or delete A's row even though he knows its id.
Back as User A: GET /expenses/1 → 200, untouched. Bob's attacks never landed.

Bob is a perfectly valid, authenticated user — and still can't touch A's data. That's the gap closed, and it's the difference between authentication and authorization made concrete. Passing this test is the moment the phase actually ended.

Stuff I want to remember [the honest takeaways]

Never store a password. Store a one-way hash. Hashing ≠ encryption — there's no "decrypt" button, and that's the point.
bcrypt is deliberately slow and auto-salted — same password, different hash every time.
A JWT's payload is readable, not encrypted. Never put secrets in it. What it gives you is integrity, guarded by a signature only your server can produce.
The SECRET_KEY leaking = total auth bypass. It lives in .env, never in git, and it's generated with real randomness.
Short token expiry [exp] limits the damage of a stolen token.
401 = "you failed to authenticate." For "that's not yours," return 404, not 403 — 403 leaks that the thing exists.
Keep login and validation errors vague and identical — specific ones leak which emails/rows exist [user enumeration].
Put the ownership filter in the query [.where(user_id == current_user.id)], not in an afterthought check you can forget.
os.getenv reads env vars; load_dotenv() loads the .env file. Different jobs — you need both.
Dependencies must be defined above the endpoints that use them — default args evaluate at def time.
Read tracebacks bottom-up; the last line is the real error. It'll save you from fixing the wrong thing.
grep before you delete. Confirm dead code is actually dead.
Freeze after every install — and sometimes you have to pin a version [bcrypt==4.0.1] to keep an older library happy.
When you cut a corner, label it — and Phase-N-later, actually go back and pay it off. DEV_USER_ID, you will not be missed.

Next up: Phase 4. The app now has a memory, a mouth, and a lock on the door. It knows who you are and only shows you your own stuff. What it doesn't have yet is a way to make sense of all that data at scale — filtering, sorting, pagination, maybe some summaries. If Phase 3 gave the app a bouncer, Phase 4 teaches it to actually organize the room. See you there.

Teaching My Backend to Listen and Reply — FastAPI CRUD, Phase 2

Azhar Alvi — Wed, 22 Jul 2026 09:38:53 +0000

Validate what comes in, shape what goes out, and give every outcome its proper status code.

So Phase 1 gave my app a memory — a real database that remembers users and expenses even after a restart. Small problem: the only way to actually talk to it was a Python script I ran by hand. The app could remember things, but it was mute. Nobody on the internet could add an expense, list their spending, or delete a typo.

Phase 2 fixes that. This is where the app grows a mouth — real HTTP endpoints you hit through the browser. The buzzword is CRUD: Create, Read, Update, Delete. The four things basically every app does to data. I went in thinking "it's just four functions, how hard can it be" and came out having learned about request/response contracts, dependency injection, and roughly six different HTTP status codes — mostly by triggering them wrong first. Let me dump what I learned [and the parts that tripped me up, because there were, uh, several].

The Structure is as follows. Lets call it PHASE 2 — The Endpoints:

Set up the request/response contracts (two Pydantic schemas: one for input, one for output)
Build a session dependency so every request gets a safe, auto-closing DB connection
POST — create an expense
GET — list them all + fetch one [with a proper 404]
PATCH — update just the fields that changed
DELETE — remove one cleanly

First, the two new ideas [and no, nothing to install this time]

Phase 1 had two new libraries. Phase 2 has two new ideas — and the nice part is there's nothing to pip install, because Pydantic already ships inside FastAPI. [Which means requirements.txt didn't change this phase. Still worth knowing the freeze habit is only for phases where you actually install something.]

Pydantic — the bouncer at the door. Your SQLAlchemy models describe how data is stored; Pydantic describes the shape data must have to cross the border of your API. It checks types, rejects garbage, and turns raw JSON into a clean Python object before it gets anywhere near your database.
Dependency injection — a fancy name for a simple deal. Instead of each endpoint opening its own database session and hoping to remember to close it, you write "how to get a session" once, and every endpoint just declares "I need one." FastAPI runs it for you and cleans up after. You'll see it as Depends(...).

Step 1: Two contracts — one for input, one for output

The single biggest lesson of this phase: you do not use one model for both the data coming in and the data going out. Two separate Pydantic schemas, on purpose. This lives in a new file, schemas.py:

from datetime import date, datetime
from decimal import Decimal
from pydantic import BaseModel, ConfigDict, Field


class ExpenseCreate(BaseModel):
    """What the CLIENT is allowed to send."""
    amount: Decimal = Field(gt=0)
    description: str = Field(min_length=1, max_length=255)
    spent_on: date


class ExpenseRead(BaseModel):
    """What the SERVER sends back — includes DB-generated fields."""
    id: int
    amount: Decimal
    description: str
    spent_on: date
    created_at: datetime
    updated_at: datetime

    model_config = ConfigDict(from_attributes=True)

Why two, and not one? Because input and output have genuinely different jobs:

ExpenseCreate (input) contains only the fields a client is allowed to send. Notice what's missing: no id, no created_at, no updated_at. Those are decided by the database, not the caller. Letting a client send its own id is a classic foot-gun.
ExpenseRead (output) is what you send back, and it does include those server-generated fields.
Field(gt=0) is Pydantic validating for me: an amount of 0 or -5 gets auto-rejected with a clean error. min_length does the same for text. The bouncer, doing its job.
model_config = ConfigDict(from_attributes=True) is the one line that lets Pydantic build the output straight from my SQLAlchemy object [reading .id, .amount etc. as attributes]. In Pydantic v1 this was orm_mode; v2 renamed it to from_attributes. Just know it exists — you'll feel why it matters in Step 3.

And yep, amount stays Decimal here too. Same Phase 1 rule: money never touches a float, not even at the API boundary.

A quick detour: who owns this expense?

Before I could create anything, I hit a wall that's actually a good lesson. My Expense has a user_id foreign key — the database will reject any expense that doesn't point at a real user. But I haven't built login yet [that's Phase 3]. So… who's the owner?

The honest answer: I cheated, on purpose, and wrote down that I cheated.

DEV_USER_ID = 5  # TEMP: Phase 3 replaces this with the authenticated user

I seeded one "dev user" and hardcoded its id as the owner of every expense. In a real app the owner comes from whoever's logged in. But the whole point of learning one thing at a time is not tangling auth into CRUD. So I structured it so Phase 3 is a one-line swap: DEV_USER_ID → current_user.id. Shortcut taken, shortcut labeled.

Gotcha #1: My first attempt to seed the dev user blew up with NOT NULL constraint failed: users.name. My User model requires a name, and I hadn't given one. Same rule as always — if a column is required, you have to supply it. [Bonus: the failed insert did a clean ROLLBACK, so no half-broken row got saved. The transaction safety I read about in Phase 1, actually doing its thing.]

Step 2: The session dependency [write it once, never leak a connection]

Every endpoint needs a database session, and every session must close afterward — even if the request explodes halfway through. So instead of copy-pasting that logic into five endpoints, it goes in database.py once:

from collections.abc import Generator
from sqlalchemy.orm import Session


def get_db() -> Generator[Session, None, None]:
    db = SessionLocal()
    try:
        yield db
    finally:
        db.close()

The weird-looking part is the yield inside a try/finally. A normal function returns and it's done. This one yields the session out to my endpoint, pauses while the endpoint runs, then comes back and runs the finally block no matter what. That finally is the whole point: db.close() is guaranteed to run on success and on error, so a session can never leak. FastAPI understands this pattern and drives it for me. [I don't fully grok generators yet, and that's fine — for now: yield = "hand it out, then come back and clean up."]

Step 3: POST — create an expense [it all comes together]

This is where Pydantic, the session dependency, and my model finally click into one endpoint. It goes in main.py, where app lives:

from fastapi import Depends, status
from sqlalchemy.orm import Session
from database import get_db
from models import Expense
from schemas import ExpenseCreate, ExpenseRead


@app.post("/expenses", response_model=ExpenseRead, status_code=status.HTTP_201_CREATED)
def create_expense(payload: ExpenseCreate, db: Session = Depends(get_db)):
    expense = Expense(**payload.model_dump(), user_id=DEV_USER_ID)
    db.add(expense)
    db.commit()
    db.refresh(expense)
    return expense

Every line is pulling weight, and it took me a minute to appreciate that:

The @app.post(...) decorator is the wiring. @ means "attach behavior to this function" — here, "when a POST hits /expenses, run me." I write the logic; the decorator handles reading the request and sending the response.
response_model=ExpenseRead runs whatever I return through the output schema before sending it. This is what stops internal fields from ever leaking — even if my model grew a secret column tomorrow, only ExpenseRead's fields go out.
status_code=201 because REST says "created" is a 201, not a plain 200. Small thing, correct thing.
payload: ExpenseCreate — just by type-hinting the parameter, FastAPI auto-reads the JSON body, validates it against the schema, and hands me a clean object. I never touch raw JSON.
Depends(get_db) — the Step 2 dependency in action. I just get a ready-to-use db that closes itself.
`Expense(payload.model_dump(), user_id=DEV_USER_ID)** — model_dump() turns the validated object into a dict, **` unpacks it into the model, and I tack on the owner. [That's the one line Phase 3 will change.]
add → commit → refresh — stage it, write it, then re-read it so the DB-generated id/timestamps get populated on my object before I return it.

Gotcha #2: My first POST returned a 500 with 'ExpenseCreate' object has no attribute 'model'. The cause was a one-character typo: I'd written payload.model.dump() [a dot] instead of payload.model_dump() [an underscore]. model_dump() is a single Pydantic v2 method name, not two things chained with a dot. [If you see .dict() in old tutorials, that's the v1 name for the same thing.]

Gotcha #3: Next 500: NOT NULL constraint failed: expenses.spent_on. My Expense requires spent_on, but my input schema didn't include it, so nothing got sent for it. Fix: add spent_on to ExpenseCreate. The rule crystallized here — every required DB column must exist in the input schema. Whack-a-mole ends the moment you check your model for all its NOT NULL columns up front.

Step 4: GET — list them all, and fetch one [meet the 404]

Two reads, two conventions: GET /expenses returns a list; GET /expenses/{id} returns one.

from typing import List
from fastapi import HTTPException
from sqlalchemy import select


@app.get("/expenses", response_model=List[ExpenseRead])
def list_expenses(db: Session = Depends(get_db)):
    return db.scalars(select(Expense)).all()


@app.get("/expenses/{expense_id}", response_model=ExpenseRead)
def get_expense(expense_id: int, db: Session = Depends(get_db)):
    expense = db.get(Expense, expense_id)
    if expense is None:
        raise HTTPException(status_code=404, detail="Expense not found")
    return expense

db.scalars(select(Expense)).all() is the same SQLAlchemy 2.0 read from Phase 1, just returning the whole list.
db.get(Expense, id) is the shortcut for "fetch one by primary key" — returns the object, or None if there's no such id.
raise HTTPException(404) is the important habit. If I let None sail through, the code crashes trying to serialize nothing → a 500, which wrongly implies I broke. Instead I deliberately raise a 404 Not Found: "your request was fine, that thing just isn't here." raise [not return] stops the function dead and sends the error.

And here's the coolest thing I learned this phase, entirely by fat-fingering the docs:

Ask for /expenses/abc [a string where an int belongs] → you get a 422. FastAPI checks the path type before your function even runs and decides the request itself is malformed.
Ask for /expenses/999999 [a valid integer that doesn't exist] → you get a 404. The request was well-formed, so the function runs, finds nothing, and raises 404.

So: 422 = "your request was malformed" vs 404 = "your request was fine, the resource doesn't exist." I built both behaviors correctly without even meaning to. That distinction is going straight into my mental model.

Gotcha #4: My list endpoint gave a "cannot fetch" until I noticed I'd dropped the leading / in the route path. Added the slash, instantly worked. The kind of bug that's invisible for ten minutes and obvious the second you spot it.

Step 5: PATCH — change only what changed

Update has two flavors, and picking the right one matters:

PUT = "replace the whole resource." The client must resend every field; anything left out gets wiped.
PATCH = "apply a partial change." Send only the fields you're changing; everything else stays.

For fixing a typo in one expense, forcing the user to resend amount + description + date [PUT's demand] is clumsy. So I built PATCH. It needs its own schema where every field is optional:

class ExpenseUpdate(BaseModel):
    amount: Decimal | None = Field(default=None, gt=0)
    description: str | None = Field(default=None, min_length=1, max_length=255)
    spent_on: date | None = None

@app.patch("/expenses/{expense_id}", response_model=ExpenseRead)
def update_expense(expense_id: int, payload: ExpenseUpdate, db: Session = Depends(get_db)):
    expense = db.get(Expense, expense_id)
    if expense is None:
        raise HTTPException(status_code=404, detail="Expense not found")

    update_data = payload.model_dump(exclude_unset=True)
    for field, value in update_data.items():
        setattr(expense, field, value)

    db.commit()
    db.refresh(expense)
    return expense

X | None = None makes a field optional — "either a Decimal or nothing." [Older tutorials write Optional[Decimal]; same meaning, | None is the modern style.] Note the validation still rides along: if amount is sent, it must still be > 0.
model_dump(exclude_unset=True) is the heart of PATCH — it gives me a dict of only the fields the client actually sent, ignoring the untouched ones. Without it, an omitted field would come through as None and I'd accidentally erase existing data. This one flag avoids the whole trap.
setattr(expense, field, value) sets an attribute by a name held in a variable — the dynamic version of expense.amount = .... Since I don't know in advance which fields arrived, I loop and set each one.

Gotcha #5: Two things bit me here. First, another 500, because I typed details= instead of detail= in HTTPException — a bad keyword makes the exception itself blow up. Second, and sneakier: when I hit Execute in /docs without editing the body, my amount came back as some huge float. Turns out Swagger pre-fills the request body with placeholder sample values — clicking Execute doesn't send "nothing," it sends those placeholders. So PATCH dutifully saved a giant number. [Combined with SQLite storing Numeric as float, it looked even uglier — that tidies up on Postgres later.] Lesson: to test a partial update, edit the body down to just the field you mean, e.g. {"amount": 99.99}. exclude_unset can't exclude what Swagger auto-filled for you.

Step 6: DELETE — remove one, return nothing

Last verb, and it introduces one more status code:

@app.delete("/expenses/{expense_id}", status_code=status.HTTP_204_NO_CONTENT)
def delete_expense(expense_id: int, db: Session = Depends(get_db)):
    expense = db.get(Expense, expense_id)
    if expense is None:
        raise HTTPException(status_code=404, detail="Expense not found")
    db.delete(expense)
    db.commit()
    return None

204 No Content is the convention for a successful delete: "it worked, and there's deliberately nothing to send back." That's why this endpoint has no response_model — there's no resource left to shape.
db.delete() + db.commit() is the destructive bit. Once committed, the row is gone — no undo. So I tested it on a throwaway expense, deleted it [204], then GET-ed the same id to confirm it returned a clean 404. Gone means gone.

One non-code head-scratcher [worth writing down]

At one point 127.0.0.1:8000/docs took ages to load and I assumed my code was broken. It wasn't. /docs is Swagger UI, and by default FastAPI tells your browser to download Swagger's JS/CSS from a public CDN — which crawls on a slow or corporate/proxied network. My actual API was instant [hitting /expenses directly proved it]. Nice reminder: a slow docs page is not a slow app. [The production fix is self-hosting those assets, but that's polish for a later hardening phase.]

Stuff I want to remember [the honest takeaways]

One model for input, a different one for output. Never accept or expose fields you shouldn't.
Every required DB column must appear in your input schema — check the model up front instead of playing 500-error whack-a-mole.
Status codes carry meaning: 201 create, 200 read/update, 204 delete, 404 missing resource, 422 malformed request.
422 vs 404 is a real distinction: bad shape vs valid-but-absent.
raise HTTPException(...) [not return] is how you send an error and stop.
model_dump() is one method with an underscore. model_dump(exclude_unset=True) is what makes PATCH safe.
Write your DB-session logic once as a Depends dependency with yield/finally — never leak a connection.
Money stays Decimal all the way to the API edge.
db.delete() + commit() is permanent. Test destructive stuff on junk data.
Swagger pre-fills placeholder values — a blind "Execute" can overwrite real data.
When you cut a corner [like hardcoding the owner], write it down and leave yourself the one-line path back.

Next up: Phase 3, Authentication — where that hardcoded DEV_USER_ID finally retires. The app has a memory and a mouth; now it needs a lock on the door: registration, hashed passwords, JWT logins, and making sure no user can peek at another's expenses. If Phase 2 gave the app a mouth, Phase 3 gives it a bouncer. See you there.

My App Can Finally Remember Stuff! (Phase 1 — The Database)

Azhar Alvi — Wed, 22 Jul 2026 09:23:28 +0000

Design it on paper, model it in Python, and NEVER touch the schema by hand.

So Phase 0 got my little FastAPI app running. One route, one JSON response, a lot of pride. But here's the thing nobody warns you about: that app had the memory of a goldfish. Restart it and… nothing. No users, no data, no clue who anyone is.

Phase 1 fixes that. This is where the app gets an actual database — a place to remember things. And honestly? This is where "I'm following a tutorial" started turning into "oh, I kind of get how backends work now." I went in knowing zero SQL. Came out having designed tables, built models, run a real migration, and read/written actual data. Let me dump what I learned [and the parts that tripped me up, because there were a few].

The Structure is as follows. Lets call it PHASE 1 — The Data Layer:

Get the right tools installed in the right place (SQLAlchemy + Alembic)
Design the tables on paper BEFORE writing any code
Turn that design into Python models
Wire up the database connection
Set up Alembic and run my first migration
Actually write and read a row [the payoff!]

First, the two new toys

Two libraries do the heavy lifting here:

SQLAlchemy — the ORM. Fancy word, simple job: it lets me talk to the database in Python instead of writing raw SQL. I write session.add(user), it writes the INSERT for me.
Alembic — the migration tool. Think of it as git, but for the shape of your database. Every time I change the table structure, it saves that change as a numbered file I can replay or roll back.

source venv/Scripts/activate      # Windows/Git Bash = Scripts/, not bin/ [learned this the hard way in Phase 0]
pip install sqlalchemy alembic
pip freeze > requirements.txt

Gotcha #1: I first installed these in a random throwaway folder, then wondered why my real project couldn't see them. Turns out a virtual environment is per-folder — packages installed in one venv are invisible to another. Reinstalled in the actual project. Lesson: check for (venv) in your prompt and make sure it's the right one before you install anything.

Step 1: Draw it on paper (yes, really)

Before touching code, I sketched two boxes:

USERS                              EXPENSES
  id       (primary key)             id         (primary key)
  name                               amount     (money)
  email    (unique)                  description
  created_at / updated_at            spent_on   (the date)
                                     user_id  --> points to USERS.id
                                     created_at / updated_at

The two ideas that made everything click:

A primary key (id) is just a unique, auto-numbered tag for each row. Names repeat, IDs don't.
A foreign key (user_id) is a column that stores another table's id. That's the whole magic of relational databases — Azhar's expenses all carry his user_id, so the DB always knows whose lunch was whose.

Sounds obvious now. Was NOT obvious an hour earlier.

Step 2: Turn the drawing into models

This is models.py — basically my paper sketch, but in Python. One class = one table.

from datetime import date, datetime
from decimal import Decimal

from sqlalchemy import MetaData, String, DateTime, Numeric, Date, ForeignKey, func
from sqlalchemy.orm import DeclarativeBase, Mapped, mapped_column, relationship


NAMING_CONVENTION = {
    "ix": "ix_%(column_0_label)s",
    "uq": "uq_%(table_name)s_%(column_0_name)s",
    "ck": "ck_%(table_name)s_%(constraint_name)s",
    "fk": "fk_%(table_name)s_%(column_0_name)s_%(referred_table_name)s",
    "pk": "pk_%(table_name)s",
}


class Base(DeclarativeBase):
    metadata = MetaData(naming_convention=NAMING_CONVENTION)


class User(Base):
    __tablename__ = "users"

    id: Mapped[int] = mapped_column(primary_key=True)
    name: Mapped[str] = mapped_column(String(100))
    email: Mapped[str] = mapped_column(String(255), unique=True, index=True)
    created_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), server_default=func.now())
    updated_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), server_default=func.now(), onupdate=func.now())
    expenses: Mapped[list["Expense"]] = relationship(back_populates="user")


class Expense(Base):
    __tablename__ = "expenses"

    id: Mapped[int] = mapped_column(primary_key=True)
    amount: Mapped[Decimal] = mapped_column(Numeric(10, 2))
    description: Mapped[str] = mapped_column(String(255))
    spent_on: Mapped[date] = mapped_column(Date)
    user_id: Mapped[int] = mapped_column(ForeignKey("users.id"), index=True)
    created_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), server_default=func.now())
    updated_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), server_default=func.now(), onupdate=func.now())
    user: Mapped["User"] = relationship(back_populates="expenses")

A few things I picked up here that felt like "real developer" moments:

Money is NEVER a float. Ever. Floats can't hold 0.10 + 0.20 exactly [it comes out as 0.30000000000000004, I'm not kidding], so over enough expenses your totals drift. Store it as Numeric(10, 2) → Python Decimal. Exact, always.
Every table gets created_at and updated_at. You will always, always want to know when something was made or changed.
The type annotation controls nullability. Mapped[str] = required. Mapped[str | None] = optional. Neat.
Those two relationship(...) lines aren't columns — they're just Python convenience so I can write user.expenses and get a list back without writing a query. The actual link is still the user_id foreign key.

Gotcha #2: I originally named the expense date column date. Bad idea — naming a column the same as its Python type (date: Mapped[date]) confuses everything and breaks type inference. Renamed it spent_on. Moral: don't name your stuff after builtins.

Step 3: The connection [kept separate on purpose]

database.py — this is how to connect, deliberately kept apart from models.py [which is what the tables are]:

import os
from sqlalchemy import create_engine
from sqlalchemy.orm import sessionmaker

DATABASE_URL = os.getenv("DATABASE_URL", "sqlite:///./expenses.db")
connect_args = {"check_same_thread": False} if DATABASE_URL.startswith("sqlite") else {}

engine = create_engine(DATABASE_URL, echo=True, connect_args=connect_args)
SessionLocal = sessionmaker(bind=engine, autoflush=False, autocommit=False)

Why the os.getenv dance instead of just hardcoding the path? Because future-me deploying to a real Postgres database will just set an environment variable and NOT have to change a single line of code. Same reason secrets live in .env. One source of truth. Also — echo=True prints every SQL statement the ORM generates, which is weirdly satisfying to watch.

Oh, and before creating any of this I added *.db and *.sqlite3 to .gitignore. The database file is local junk data — it has no business in my repo. [And yeah, same "before it exists" trick I used for .env — git can't accidentally track what it was already told to ignore.]

Step 4: Alembic and my first migration

Here's the part I was low-key scared of, and it turned out to be the coolest bit.

alembic init alembic     # creates the migration setup

Then I pointed Alembic at my project in alembic/env.py — told it where my models live and where the database is:

from database import DATABASE_URL
from models import Base

config.set_main_option("sqlalchemy.url", DATABASE_URL)
target_metadata = Base.metadata

This is the important bit: Alembic's autogenerate works by comparing my models to the actual database and writing the difference. target_metadata is how it "sees" my models. Without it, it detects nothing.

I also added that NAMING_CONVENTION thing (up in models.py) BEFORE generating anything. Why bother? Because otherwise the database invents random names for your constraints/indexes — and SQLite often gives them no name at all. Then a future migration that needs to change one has nothing to grab onto. Set the convention early, and everything gets clean, predictable names like fk_expenses_user_id_users. Set-it-and-forget-it.

Then the magic command:

alembic revision --autogenerate -m "create users and expenses tables"

And it wrote the migration for me — two create_table calls, the foreign key, the indexes, plus a matching downgrade() that undoes it all. I read the whole file before running it [apparently this is a habit real teams enforce — autogenerate isn't perfect, so you always eyeball it first]. Looked right. So:

alembic upgrade head     # actually builds the tables
alembic current          # shows my revision with (head) = up to date

Watching the real CREATE TABLE SQL scroll past because of echo=True? Chef's kiss. That was the "oh, THIS is what an ORM does" moment.

Gotcha #3: My -m message accidentally said "expense" (singular), so the migration filename said expense too — and I panicked thinking the tables were wrong. They weren't. The -m text is just a label; the real table names come from __tablename__. Totally cosmetic.

Gotcha #4: When I pasted my code into an email, Gmail helpfully turned users.id into a clickable link http://users.id/. Nearly gave me a heart attack. It's just email being email — the real file was fine. Check your code in the editor, not in email.

Step 5: The payoff — write a row, read it back

from decimal import Decimal
from datetime import date
from sqlalchemy import select
from database import SessionLocal
from models import User, Expense

with SessionLocal() as session:
    user = User(name="Azhar", email="azhar@example.com")
    session.add(user)
    session.commit()            # NOW it's in the DB, and user.id gets assigned

    session.add(Expense(
        amount=Decimal("12.50"), description="Lunch",
        spent_on=date.today(), user_id=user.id,
    ))
    session.commit()

    fetched = session.scalars(select(User)).first()
    print(fetched.id, fetched.name, [(e.description, e.amount) for e in fetched.expenses])

And it printed my user and their lunch. My app remembers things now. 🎉

Couple of things worth knowing:

Nothing actually hits the database until commit(). That's also when the primary key gets assigned — which is exactly why I commit the user before the expense that needs its id.
Decimal("12.50") uses quotes on purpose. Decimal(12.50) [no quotes] would drag the float imprecision back in. Little detail, big deal for money.
select(User) with session.scalars(...) is the modern SQLAlchemy 2.0 way. If you see session.query(...) in older tutorials, that's the legacy style.

Gotcha #5: Ran the script a second time and it blew up with an IntegrityError on the email. That's not a bug — it's my unique constraint literally doing its job and refusing a duplicate. Honestly kind of reassuring to see it work.

Stuff I want to remember [the honest takeaways]

Design on paper first. The code is just the drawing, translated.
Money is Decimal/Numeric, never float. Build it from a string.
Give every table created_at / updated_at.
Never hardcode the database URL — read it from an env var.
NEVER edit the database structure by hand. Models → migration, every single time.
Always read an autogenerated migration before you run it.
Set your naming convention before the first migration, not after.
Virtual environments are per-project. Install in the right one. Freeze requirements.txt after every install.
Ignore .db files and secrets before they exist. And always commit your migration files — they're the schema's shared history.
Keep echo=True on while learning so you can actually see the SQL. It demystifies everything.

Next up: Phase 2, where I turn all this into real API endpoints [POST an expense, GET the list, the whole CRUD gang]. If Phase 1 gave the app a memory, Phase 2 gives it a mouth. See you there.

Phase 0 : Building My First FastAPI App: Setup, Git, and Secrets Done Right

Azhar Alvi — Thu, 16 Jul 2026 18:57:38 +0000

Tagline: Commit small, commit often, write real messages.

Creating a hello-world app sounds easy — and it is. But doing it the right way, with proper git hygiene, isolated environments, and secrets handled safely from day one? That takes a bit more care. Here's what I actually did, step by step, and why.

Index

Introduction
Structure of this log
Step 1: Project Foundations
- Create the folder
- Initialize git first
- Create .gitignore before installing anything
- Create and activate the virtual environment
- Install packages + freeze requirements
- First commit
- Connect to GitHub
- The repeatable loop
- The commit flow, in isolation
Step 2: Getting FastAPI Running Locally
- Ensure the virtual environment is active
- Install FastAPI and Uvicorn
- Create the app file
- Start the server
- Check the automatic docs
Step 3: Secrets — the .env File
- Create .env
- Confirm it's actually ignored
Step 4: Start This Build Log
Key Habits to Keep

Introduction

I started learning backend dev properly this week, and today I got a hello-world FastAPI app running locally. Nothing fancy — one route, one JSON response — but I wanted to write down what actually happened along the way, because "install a package and run a command" always looks simpler in hindsight than it feels in the moment.

Structure of this log

Create project folder → init git → .gitignore → virtual environment
Connect to a GitHub repo
Build and run a FastAPI hello-world app, explore /docs
Set up a .env file for secrets and confirm it's gitignored
Start this build log

Step 1: Project Foundations

Create the folder

mkdir my-project-1
cd my-project-1

Initialize git first

git init

Why first? So every file created from this point on is tracked from day one — no risk of forgetting to init later.

Create `.gitignore` before installing anything

cat > .gitignore << 'EOF'
venv/
__pycache__/
.env
.DS_Store
EOF

Why before the virtual environment? If you create the venv first, git could briefly see hundreds of library files before you've excluded them. Doing this first avoids ever accidentally staging things you don't want tracked.

How this command works:

cat — normally reads and displays file content, but here it's not reading a file — it's about to receive typed input instead.
> — redirect operator. Instead of printing to the screen, the output is written into a file. Since .gitignore doesn't exist yet, this creates it.
<< 'EOF' — a heredoc. It tells bash: "don't wait for a real file — treat everything typed next, up until a line that says exactly EOF, as the input text."
EOF (closing) — signals "stop, that's the end of the input."

Note: EOF isn't a special keyword — it's just a convention. You could use BANANA instead, and it would work identically: bash treats everything as raw text until it sees a line containing exactly that word. EOF ("End Of File") is used everywhere because it instantly signals intent to anyone reading the script.

Note: This heredoc syntax is bash-specific. PowerShell uses a different syntax (@" ... "@ | Out-File) — match the syntax to the shell you're actually in.

Create and activate the virtual environment

python -m venv venv
source venv/Scripts/activate

What this does:

python -m venv venv — runs Python's built-in venv module, creating a folder (venv/) containing an isolated copy of Python and its own package directory.
source venv/Scripts/activate — activates it, redirecting your terminal's python/pip to point inside venv/ instead of your system-wide install. You'll know it worked when (venv) appears in your prompt.

Note: The folder is named Scripts/ on Windows and bin/ on Linux/macOS. If source venv/bin/activate fails with "No such file or directory," check which one actually exists with ls venv.

Install packages + freeze requirements

pip install requests
pip freeze > requirements.txt

Why this matters: every time you install something new, freeze it into requirements.txt. This makes the exact dependency set shareable — anyone (including future-you) can recreate your environment with pip install -r requirements.txt.

First commit

touch README.md main.py      # or: New-Item README.md, main.py   (PowerShell)
git add .
git commit -m "Initial project setup"

What makes a good commit message: it describes what changed and why — not just "update" or "fix stuff."

Connect to GitHub

Create a new, empty repository on GitHub first, then:

git remote add origin <your-repo-url>
git branch -M main
git push -u origin main

Breaking this down:

Command	What it does
`git remote add origin <url>`	Registers a remote connection, nicknamed `origin` (convention), pointing at your GitHub repo's URL. No data moves yet — this just registers the address.
`git branch -M main`	Renames your current branch to `main` (forcing it even if a branch with that name exists), matching what GitHub expects by default.
`git push -u origin main`	Uploads your commits to GitHub for the first time. `-u` sets up tracking between local `main` and `origin/main`, so every push after this can just be `git push`.

Run this sequence once per project — right at the start, connecting a fresh local repo to a fresh GitHub repo.

The repeatable loop (used for every session after this)

source venv/Scripts/activate
# ... work, install packages ...
pip freeze > requirements.txt
git add .
git commit -m "clear description of change"
git push
deactivate

The commit flow, in isolation

git status                          # check what changed
git add .gitignore                  # stage the change
git commit -m "clear description"   # commit with a real message
git push                            # push to GitHub
git log --oneline -1                # sanity check

Step 2: Getting FastAPI Running Locally

Ensure the virtual environment is active

source venv/Scripts/activate

Install FastAPI and Uvicorn

pip install fastapi uvicorn
pip freeze > requirements.txt

FastAPI — lets you define API routes/endpoints in Python. It doesn't serve requests on its own — it needs an ASGI (Asynchronous Server Gateway Interface) server to actually run.
Uvicorn — a lightweight ASGI server that runs your app and listens for HTTP requests.

Create the app file

code .   # opens the current folder in VS Code

Structure of main.py:

Import FastAPI
Create an application instance (app = FastAPI()) for Uvicorn to run
Use a decorator (@app.get("/")) so that a GET request to the root URL runs the function below it
Define the function to handle the request
Return the response (FastAPI auto-converts a Python dict to JSON)

from fastapi import FastAPI

app = FastAPI()

@app.get("/")
def read_root():
    return {"message": "Hello, World!"}

Start the server

uvicorn main:app --reload

main:app — tells Uvicorn to look inside main.py for an object named app.
--reload — automatically restarts the server whenever you save a code change.

Visit http://127.0.0.1:8000 to see the JSON response.

Check the automatic docs

Visit http://127.0.0.1:8000/docs — FastAPI auto-generates a full interactive API explorer (Swagger UI / OpenAPI spec), built entirely from your route definitions. No docs code required.

A read-only alternative view is available at /redoc.

Step 3: Secrets — the `.env` File

Create `.env`

cat > .env << 'EOF'
APP_SECRET=super-secret-value-123
EOF

Confirm it's actually ignored — don't just assume

git status                 # .env should not appear anywhere in the output
git check-ignore -v .env   # the definitive test

git check-ignore -v reports exactly which line in which file is causing the file to be ignored, e.g.:

.gitignore:7:.env    .env

Important: .gitignore only prevents git from tracking files it hasn't already started tracking. If a secret was committed before being added to .gitignore, it will still exist in your git history. Setting up the ignore rule before the first git add — which is what happened here — avoids this entirely.

Step 4: Start This Build Log

Keep two documents, for two different audiences:

BUILD_LOG.md (this file) — chronological, for future-me. What I did, what broke, what I learned. Terse is fine.
README.md — for other people (or future-me pretending to be someone else). What the project is and how to run it — a snapshot of current state, not a diary.

The most useful log entries capture the why, not just the what — especially for snags:

## 2026-07-16

- Set up project folder, git repo, and Python virtual environment
- Installed FastAPI + Uvicorn, built a hello-world app with a single GET / route
- Confirmed it runs locally and explored the auto-generated /docs (Swagger UI)
- Set up a .env file for secrets and confirmed it's properly gitignored
  (learned: .gitignore only blocks files git hasn't tracked yet — order matters)

Commit it the same way as everything else:

git add BUILD_LOG.md
git commit -m "Start build log with first entry"
git push

Key Habits to Keep

Commit small, commit often, write real messages — a message should answer "what changed and why," not just "update."
.gitignore before git add, always — order of operations is what actually protects secrets.
Freeze requirements on every install, not just at the end.
Log the "why" and the snags, not just the "what" — that's the part future-you will actually forget.

DEV Community: Azhar Alvi

Phase 8 — Making It Trustworthy: Hardening a FastAPI App with an Audit, a Test Net, and a Logging Bug I Typed Twice

Index

Where we left off

The plan: prove it, then protect it

Step 1 — The warm-up: a /health endpoint

Step 2 — The audit: probe my own API for leaks

Step 3 — The safety net: a global exception handler

Step 4 — The test net: turning manual proofs into permanent ones

Step 5 — The isolation test: an in-memory database that lies convincingly

Step 6 — Pagination: putting a ceiling on an unbounded list

Step 7 — The secrets sweep: is anything sensitive in my git history?

The war story: the tool does what you type, not what you mean

Gotcha 1 — the logging placeholder I fat-fingered twice

Gotcha 2 — a test that never ran

Gotcha 3 — the login that failed on one capital letter

Gotcha 4 — the terminal's invisible passengers

Thinking like an attacker

Learning shortcut vs. production

Key habits to keep

Next up: Phase 9

Phase 7b — Bolting On the AI: An LLMCategorizer Behind the Same Door (with Caching, a Fallback, and Six Model Names)

Index

Where we left off

The plan: everything behind the same contract

Step 1 — The toggle: a factory and an env var

Step 2 — The stub: prove the wiring before the call

Step 3 — The real call: constrained prompt, validation, fallback

Step 4 — Caching: don't pay for the same Starbucks twice

One loose end: the CSV finally learned about categories

The war story: six model names and a comma

Gotcha 1 — the comma that lived in my .env

Gotcha 2 — --reload doesn't watch .env

Gotcha 3 — "No module named 'google'" — the environment, not the folder

Gotcha 4 — the silent except that hid a dead LLM

Gotcha 5 — six model names

Thinking like an attacker

Learning shortcut vs. production

Key habits to keep

Next up: Phase 8

Phase 7a — Getting Opinionated: Rules-Based Auto-Categorization (and a Seam for the AI Later)

Index

Where we left off

The plan: rules first, AI behind the same door

Step 1 — A nullable column (and why nullable matters)

Step 2 — The migration: generate → review → apply

Step 3 — A dumb-but-working categorize()

Step 4 — Wiring it into create (with override precedence)

Step 5 — The seam: extracting behind a Categorizer interface

Step 6 — The UI loop: show, add, edit

🐛 The war story: three ways "empty" lied to me

Gotcha 1 — Nullable ≠ optional (the silent 422)

Gotcha 2 — Empty string sneaks past the categorizer

Gotcha 3 — "Today" was yesterday (a UTC off-by-one)

Thinking like an attacker

Learning shortcut vs. production

Key habits to keep

Next up: Phase 7b

Phase 6 — Give Me the Receipts: Date-Range Reports & CSV Export in FastAPI

Introduction

Index

Structure of this log

Step 1: The date-range report endpoint

The rule I learned for query params

Two layers of validation

Inclusive range vs the half-open trick

The endpoint

How I tested it (the adversarial pass)

Step 2: The CSV export endpoint

Idea 1 — the csv module

Idea 2 — io.StringIO, a file that lives in memory

Idea 3 — StreamingResponse + download headers

The endpoint

The bug: my CSV only had one row

Step 3: Don't Repeat Yourself — extracting a shared helper

Step 4: The Export CSV button (why a plain link won't work)

Key habits to keep

Phase 5: The Numbers Start Talking

The roadmap collision [the field I did not have]

Gotcha #15 — A roadmap dependency is not permission to lie to your model

Step 1 — The warm-up: a `/health` endpoint

Gotcha 1 — the comma that lived in my `.env`

Gotcha 2 — `--reload` doesn't watch `.env`

Gotcha 4 — the silent `except` that hid a dead LLM

Step 3 — A dumb-but-working `categorize()`

Step 5 — The seam: extracting behind a `Categorizer` interface

Idea 1 — the `csv` module

Idea 2 — `io.StringIO`, a file that lives in memory

Idea 3 — `StreamingResponse` + download headers

`func.sum(...)`

`db.scalar(...)`

Gotcha #16 — `SUM()` over no rows does not naturally give zero