I want to press the diagram’s button six times

The sixth press

Five presses send five objects through. What happens on the sixth? If I were designing a diagram to explain request limiting, I would start with that moment.

Reading Anatomy’s README suggested this exercise. It describes interactive isometric explanations with readouts connected to an underlying model. This is a proposed design for an explanation, rather than an account of running the tool.

A bucket fills with coins; each passing request takes one. The name token bucket has already supplied the props. Drawing an attractive bucket could feel like half the explanation.

Watching it fill, though, reveals little about what I have understood. Give me a button and I can choose an awkward moment myself.

Borrow a clock

For an imagined demonstration, start with five credits, cap them at five, replenish one per second, and charge one per request. Send six requests at one simulated instant. Reject insufficient requests immediately; provide no queue.

Five pass and one fails. A minute without requests still leaves only five credits. This adapts the cap and balance check in RFC 3290, Appendix A.4, from packet sizes to request units; it is not an API implementation specification.

I would give this scene a simulated clock. Six manual clicks take time, during which credits might replenish. One control would submit six simultaneous requests; another would advance time.

The explanation says the sixth request fails, but the presenter clicks slowly enough for it to pass. I would prefer not to explain that discrepancy beside an otherwise polished animation.

Slowing the animation should not accidentally alter the example’s calculation either. Before drawing flying coins, I would decide how presentation time relates to simulated time.

Draw a line and people expect to wait

The prop I would handle most carefully is the line beside the bucket. Represent requests as people or boxes and it becomes tempting to leave unsuccessful arrivals standing neatly at the gate.

That invites an expectation: wait and you will get through. Our sixth request has already been rejected. Leaving it at the entrance could suggest that the next credit will process it automatically.

I would move that box aside. Another attempt would require another request. If I wanted to explain waiting, I would introduce a queue explicitly. A small addition to the drawing can promise another behavior.

The distinction can sound dry in prose. In a picture, changing where a box goes raises a very immediate question: is that request still pending, or must I send it again?

So after specifying colors and composition, I would write down where an unsuccessful box should end up.

Let me change one thing

I would first hold capacity at five and let the reader change replenishment speed. Then hold speed steady and change capacity. Moving both controls together would leave us explaining which change caused the result.

I would also leave room for a prediction. Instead of playing the outcome automatically, pause after submission and let the reader decide which boxes will pass. That could open a different conversation from watching an answer and nodding.

I have not measured a learning benefit here. These are controls I would try when preparing an explanation. The small scene would not claim to cover concurrency or recovery in a distributed production service.

Polishing the bucket’s shadow sounds enjoyable too. But if the sixth box quietly slips through while the shadow gets prettier, my hand will probably move toward that box.

I would stop the clock and press the button once more, watching where it goes.

Sources

• Anatomy — interactive technical illustrations
• RFC 3290 — Appendix A.4, token balance and capacity