I Built an Interactive Visualizer of the Spring Boot Request Lifecycle

Every Spring tutorial teaches you the annotations — @RestController, @Service, @Repository — but almost none show you the journey a single HTTP request takes between them. Where does the front controller sit? When does @Valid short-circuit? Where exactly is a 404 born?

So I built an interactive visualizer that animates the whole thing, right in the browser.

▶ Live demo: https://dev48v.github.io/spring-request-flow/
Source (zero dependencies): https://github.com/dev48v/spring-request-flow

Click an endpoint, hit Send, and watch the request flow down through every layer and back up as JSON — with a live trace log and the real response.

The chain, top to bottom

When a request hits a Spring Boot app, it doesn't go straight to your controller. It travels:

1. Client sends the HTTP request.
2. Tomcat (the embedded servlet container) accepts the socket and builds an HttpServletRequest.
3. Filter chain runs first — CORS, encoding, Spring Security. This is before any controller code.
4. DispatcherServlet — the one front-controller servlet that routes every request in the app.
5. HandlerMapping matches the URL + verb to a specific controller method.
6. Controller (@RestController) — a thin web layer: bind params, return a ResponseEntity.
7. Bean Validation (@Valid) — checks the @RequestBody against your constraints. On a GET there's no body, so this step is skipped.
8. Service (@Service @Transactional) — business rules, and the transaction boundary opens here.
9. Repository (Spring Data JPA) — an interface method name becomes a SQL query.
10. Database — Hibernate runs the SQL over a pooled HikariCP connection.

On the way back up: rows become an OrderEntity, which is mapped to an OrderResponse DTO, wrapped in a ResponseEntity, serialized to JSON by Jackson, and sent back out through the filter chain.

The part most people get wrong: the error path

The most useful scenario in the demo is the 404. People assume the controller checks "does this exist?" and returns a 404. It doesn't.

What actually happens for GET /api/orders/0000:

• The request goes all the way down to the database — which returns zero rows.
• The repository returns Optional.empty().
• The service sees the empty Optional and throw new OrderNotFoundException(...).
• That exception bubbles up and is caught by a @RestControllerAdvice, which maps it to an RFC-7807 ProblemDetail with status 404.

The 404 is thrown, not returned — and a single advice class turns every exception into a clean JSON error. The demo lights this whole path up in red so you can see it.

A 400 is different again: it short-circuits at the validation layer. The service never runs. The demo shows that too.

Why a visualizer instead of a diagram

Static architecture diagrams show you the boxes. They don't show you order, timing, or where things stop. Watching a request actually move — and watching a bad request die early — is what made these concepts click for me.

It's one index.html, no build step, no framework. Open it and read the whole thing in a sitting.

If it helps you understand Spring, a star on the repo helps others find it: https://github.com/dev48v/spring-request-flow