LLDadvancedPremium

Building a Rate Limiter: The Low-Level Design

A low-level design walkthrough of a rate limiter: the token bucket class, the race condition that breaks it, making it thread-safe, a per-client registry, and the complete implementation.

By fiveyearsdevJune 11, 202611 min read

In the high-level design we drew a box labelled rate limiter, parked it inside the API gateway, and moved on. Interviewers love doing the opposite: "open that box. Build everything inside it." Suddenly it's not about Redis and load balancers anymore — it's about classes, state, and the one race condition that silently breaks the naive version. That's this article. By the end, you and I will have built the whole box: the contract, the bucket, the per-client registry, the web wiring — and we'll have personally watched the concurrency bug happen before we fix it. Starting cold? The companion a…

What’s inside

Let's start nowhere near a computer

Where this exact code runs

Step 1 — Functional requirements (the contract)

Step 2 — Non-functional requirements

Step 3: the bucket's state — three fields, two decisions

Step 4: lazy refill — the clock does the work

Step 5: watch the race break it

Step 6: one bucket per client — the registry

Step 7: the memory leak nobody mentions

Step 8: wiring it into the request path

The trade-offs you should be able to defend

The complete implementation

Where to go from here

Read this one free

LLD