One FastAPI Backend, Four Roles: Architecture Notes from Building Chowzee
A delivery platform looks like one product from the outside. From the inside it is four products that share one set of rules: the customer who orders, the restaurant that cooks, the rider who delivers and the admin who keeps the marketplace honest. I built all four of those surfaces, plus the API behind them, for a food-delivery platform called Chowzee. This post covers the backend decisions that mattered most.
The stack: FastAPI, Pydantic v2, SQLAlchemy 2.0 and Alembic on PostgreSQL, with Supabase handling auth and storage. The API ended up with 79 endpoints and 14 migrations.
Verify tokens locally, not over the network
Supabase issues the JWTs, but the API does not call Supabase to check them. It verifies each token against the project's public JWKS, which is cached, so authentication costs no network round trip per request.
# Simplified: resolve the signing key from the cached JWKS, then verify.
signing_key = jwks_client.get_signing_key_from_jwt(token)
claims = jwt.decode(token, signing_key.key, algorithms=["RS256", "ES256"], audience="authenticated")
If a profile row does not exist yet for a valid token, the API creates one on first sight. Every user starts as a plain customer. Becoming a rider or a restaurant owner goes through an application flow, never through something the client can set on itself.
Roles as dependencies, not scattered if-statements
Every router declares which role it serves, and FastAPI dependencies enforce it before the handler runs:
def require_role(*roles: str):
def checker(user: Profile = Depends(current_profile)) -> Profile:
if user.role not in roles:
raise HTTPException(status_code=403, detail="Forbidden")
return user
return checker
@router.get("/admin/orders", dependencies=[Depends(require_role("admin"))])
def list_all_orders(...): ...
The status codes are deliberate and consistent, which makes the clients simpler:
- 401 for a missing or invalid token
- 403 for a valid user touching someone else's data or the wrong role's endpoints
- 409 for an invalid state transition, such as accepting an order that was already cancelled
Two lifecycles, not one
The most useful modelling decision was splitting the order from the delivery.
- An order belongs to the restaurant side: placed, accepted, preparing, ready for pickup, completed (or rejected, or cancelled).
- A delivery belongs to the rider side: assigned, to pickup, to drop-off, delivered.
With one combined status field, a rider who drops out mid-trip would force you to rewrite the order's history. With two tables, the delivery is simply reassigned to another rider and the order's history stays untouched.
Never trust the client for money
Subtotals, add-on pricing, delivery fees, promo-code discounts and loyalty-point redemption are all computed on the server from catalogue prices. The client sends item IDs, quantities and selected add-on IDs, and the API prices everything itself. A modified app cannot change what an order costs.
Referral bonuses follow the same rule: both sides are paid out only once the referred user's first order is actually delivered, and the payout is guarded so it can fire at most once.
Approval gates for a two-sided marketplace
Restaurants and riders both start as pending:
- A pending restaurant is invisible in the public catalogue until an admin approves it.
- A pending rider cannot go online.
The admin console lists applications, approves or suspends partners, and shows a platform-wide order feed. Because the rule lives in the API, none of the clients can skip it.
Boring scheduled jobs
Scheduled orders need something to release them at the right time. At this scale I did not want a queue and worker fleet, so there is a single internal endpoint protected by a shared secret, triggered every five minutes by a GitHub Actions workflow. It is one less piece of infrastructure to run, and it is easy to reason about.
What I would tell my past self
- Put authorization in dependencies so every endpoint states who can call it.
- Model lifecycles separately when different actors own them.
- Let the server own prices, totals and bonuses.
- Keep infrastructure proportional to the problem. A cron-triggered endpoint is enough for a lot of "background jobs".
You can see the full breakdown, with screenshots of all four products, in the Chowzee case study.