Finance API:
Backend Tracker

FIVE ROUTERS, 31 ROUTES

Four of the five routers call router.use(authMiddleware) once at the top rather than decorating each route. Adding a route to one of them cannot accidentally ship it unauthenticated, because authentication is a property of the router and not something the author has to remember.

12 QUERY PARAMETERS ON ONE ENDPOINT

The search schema is where most of the API's expressiveness lives, and it is a single Zod object rather than a hand-rolled query parser. Coercion is part of the schema — a date arrives as a string and leaves as a Date, a page number arrives as a string and leaves as a positive integer — so the service beneath never sees a string that should have been a number.

The defensive details are in the schema too rather than in the handler: limit is capped at 100 and defaults to 50, sortBy is an enum of four permitted columns rather than a free string, and three of the filters accept either an array or a single value so a one-element filter does not need special-casing by the caller.

The model

Two dates, not one

An expense carries both an expenseDate — when the money was actually spent — and an entryDate for when it was recorded. People log expenses in batches days later, and collapsing those into one timestamp makes every monthly total subtly wrong. Analytics all filter on expenseDate; the entry date exists to explain a gap, not to be reported on.

Deletion is soft. A deletedAt timestamp is set and every read adds deletedAt: null. The export endpoints are the one place that can opt back in, via an includeDeleted flag — so a user taking their data out can choose to take the history with it.

Three compound indexes back that, all led by userId: userId with descending expense date, userId with category, and userId with deletedAt. The leading field is never optional, because no query in this API is ever legitimately cross-user.

Creating an expense runs a duplicate guard first: same user, same amount, within sixty seconds either side of the given date. Double-tap on a submit button is the failure this is actually for, and it comes back as a 400 with EXPENSE_DUPLICATE_DETECTED rather than a generic validation error, so a client can offer “yes, I meant it” instead of just failing.

ERRORS ARE TYPED

Twenty error codes in one enum, grouped by concern — auth, user, expense, validation, resource, generic. Every failure response carries a machine-readable code alongside the human message, so a client branches on AUTH_TOKEN_EXPIRED versus AUTH_TOKEN_REVOKED rather than matching on English.

The error middleware separates faults it expects from faults it does not. A Zod failure becomes a 400 with a per-field list of { field, message }. An operational AppError keeps its own status and code. Anything else is a 500 whose message is replaced with “Internal server error” in production — stack traces are attached only outside production, so a crash cannot leak internals to a caller.

WHAT I'D DO DIFFERENTLY

The analytics are not aggregation pipelines. Every summary loads the matching documents with a find() and reduces them in Node — totals, category frequency maps, zero-spend day counts, and a spending-spike filter that flags anything above twice the period's mean.

At one person's expense history that is genuinely fine, and it kept the logic readable and trivially testable. It does not survive growth: the whole result set crosses the wire for what should be a single scalar. The rewrite is well-defined — $match then $group for the summaries, $facet for the rollups that currently issue four queries in parallel — and the existing indexes already support it. It has not been done because nothing has made it necessary yet, which is the honest reason rather than a design one.