Backend
A Layered TypeScript API Where Every Request Takes the Same Path
Section 3 of 5
The core API is around 9,500 lines of TypeScript across 74 modules, running on Express over Firestore. Its defining property is not any individual feature but the fact that there is exactly one way through it. Every request crosses the same sequence of boundaries in the same order, and no layer is permitted to reach past its neighbour: a router never queries the database, a service never reads an HTTP request object, a repository never knows what a user is allowed to do.
That discipline is not aesthetic. On a product where one engineer moves between eight services in a day, the cost of a codebase where you have to read a handler to find out what it touches compounds fast. Here, the location of a piece of logic is derivable from what kind of logic it is — which means changing it is a local operation, and reviewing it is a small one.
The Lil Strollr API is built on the same skeleton by design. Same layers, same repository base, same validation and authentication middleware. What it adds is commercial — Stripe subscriptions, the quota engine, server-side analytics — and the agent bridge covered in the next section.
74
modules across six architectural layers
9.5K+
lines of TypeScript
8
domain routers, each fully documented
0
layer-skipping shortcuts
Request Lifecycle
Every request descends through these layers and every response returns back up through them. Each boundary has one responsibility, and a request that fails a boundary never reaches the next one.
How Each Layer Earns Its Place
Firestore's client returns loosely typed document data. Left alone, that means every repository in the codebase performs its own casting, and a field renamed in one place fails silently in five others.
Instead there is a single abstract base class, generic over the document type, that attaches a typed converter to its collection reference on construction. Every concrete repository — users, venues, activities, sessions, chats, notifications, validations — extends it with its own type parameter and inherits typed create, find-one-by, find-many, count-by, update-by-id, delete-by-id and bulk-delete operations without writing any of them.
The bulk delete is worth calling out because the naive version is a correctness bug waiting to happen: deleting matched documents one at a time is neither atomic nor efficient. The base implementation collects the matching references and commits them as a single Firestore batch, so a multi-document delete either lands or does not.
What subclasses add is only what is genuinely specific — the venue repository's vector search, the chat repository's cursor pagination, the user repository's aggregate queries. Everything ordinary is inherited, which is why 74 modules cover this much surface area.
Offset Versus Cursor Pagination
The same request for page four, served two ways. The top path reads and discards everything before it; the bottom path seeks straight to the anchor.