Play Framework Architecture and Action Composition
How Play handles a request through the Pekko HTTP server, router, filters and actions, and how action composition adds behavior such as authentication.

Play differs from servlet frameworks in ways that surprise Java developers. There is no servlet container, no server-side session by default, and the core is asynchronous. Once the request path is clear, the rest of the framework's choices make sense. This post follows one request from the socket to the response, then covers action composition, the mechanism for sharing behaviour between controllers. If you have not seen a Play project yet, start with the Play tutorial. The version here is Play 3.
The request path
Client -> HTTP server (Pekko HTTP, Netty as an alternative)
-> HttpRequestHandler
-> Filters
-> Router (conf/routes)
-> Action (your controller method)
-> Result -> responsePlay 3 uses Apache Pekko for the HTTP server and its actor system, where Play 2.x used Akka. Pekko is the Apache-licensed continuation of Akka. The server is non-blocking: a small number of threads serve many connections, so an action must not hold one of them waiting. That is the central rule of the framework, and most Play performance problems are a violation of it. For the wider trade-offs between waiting and not waiting, see how services communicate.
The router
conf/routes is compiled into a router. Each line names a controller method with a typed signature:
GET /orders/:id controllers.OrderController.show(id: Long)
GET /orders controllers.OrderController.list(page: Int ?= 1)The router converts the path and query values to the declared types. A request for /orders/abc fails the conversion and gets a 400 before your action runs, so you do not write that check. Because routes are compiled, a reference to a method that does not exist is a build error, not a runtime surprise.
Filters
A filter wraps every request. Play ships filters for security headers, CSRF protection, allowed hosts and CORS, switched on in configuration:
play.filters.enabled += play.filters.cors.CORSFilter
play.filters.hosts.allowed = ["localhost", ".example.test"]Write your own as a class implementing play.mvc.EssentialFilter. Filters run before routing, so a filter does not know which action will handle the request. That is the difference that matters when choosing between a filter and the action composition below: use a filter for something every request needs, and composition for something only some actions need.
Actions and results
public Result profile(Http.Request request) {
return ok(Json.toJson(Map.of("user", "ana"))).as("application/json");
}A Result is an immutable value holding a status, headers and a body. An action that waits on something returns a CompletionStage<Result>, which lets the thread go while the work completes:
public CompletionStage<Result> report() {
return reports.generate().thenApply(r -> ok(r.toString()));
}Returning the stage is the whole mechanism. Calling .toCompletableFuture().get() on it inside the action turns the asynchronous call back into a blocked thread, which defeats the design.
Action composition
Behaviour attached to chosen actions uses composition. Define an annotation and an action that implements it:
@With(AuthenticatedAction.class)
@Target({ElementType.TYPE, ElementType.METHOD})
@Retention(RetentionPolicy.RUNTIME)
public @interface Authenticated { }public class AuthenticatedAction extends Action<Authenticated> {
@Override
public CompletionStage<Result> call(Http.Request request) {
if (request.session().get("user").isEmpty()) {
return CompletableFuture.completedFuture(redirect(routes.LoginController.form()));
}
return delegate.call(request);
}
}Put @Authenticated on a controller class or on one method, and the wrapping action runs first. delegate is the next action in the chain. If the check fails, the action returns its own result without calling delegate, so the controller method never runs. Several annotations compose in the order they are written. Play's counterpart to this in other frameworks is Spring's interceptors, and the Struts interceptor stack in older code.
Threads and blocking
The default dispatcher has a small pool sized to the cores. A blocking JDBC call inside an action occupies one of those threads for the duration of the query, and a handful of slow queries can leave the server unable to answer anything, with the CPU idle. The symptom is a server that stops responding under load while the machine looks calm. Run blocking work on a separate executor:
blocking-dispatcher {
executor = "thread-pool-executor"
thread-pool-executor {
fixed-pool-size = 20
}
}public class BlockingExecutionContext extends CustomExecutionContext {
@Inject
public BlockingExecutionContext(ActorSystem system) {
super(system, "blocking-dispatcher");
}
}Inject that context and pass it to CompletableFuture.supplyAsync(() -> repository.load(id), blockingContext). The pool size is a capacity decision: it caps how many queries can run at once, and should not exceed your database connection pool.
Choosing between a filter and a composed action
Both wrap a request, and picking the wrong one is the most common design slip in a Play application. A filter sees every request before routing and receives no information about the target action. It suits things that must apply to everything: adding a response header, logging a request id, rejecting a host you do not serve. A composed action sees only the requests that reach the annotated method, and it runs after routing, so it can read the route, the typed parameters and the controller annotations.
Authentication is the standard example of why this matters. If you implement it as a filter, the login page and the static assets are covered too, and you end up writing an allow list of paths that bypass it. That list grows quietly and eventually contains an entry that should not be there. With composition the rule is the opposite and safer for a team: nothing is protected until it carries the annotation, and an unprotected endpoint is visible in the controller as a method with no annotation on it. If you prefer deny by default, put the annotation on the controller class and opt out per method, or write a small base controller whose methods are all protected.
Composition also stacks. Put @Authenticated and a second annotation such as @RateLimited on the same method and the actions wrap each other in order. Keep each composed action to one concern, and test it by calling call with a fake request and a stub delegate, which needs no running server. A composed action that grows to handle authentication, auditing and feature switches becomes the filter you were trying to avoid, with less visibility.
Request attributes are how a composed action hands data to the controller. After authenticating, the action can attach the user to a copy of the request with request.addAttr(Attrs.USER, user) and call the delegate with that request, so the controller reads the user without touching the session.
Sessions without a server
Play's session is a signed cookie, not an object held on the server. request.session().get("user") reads from the cookie that arrived with the request, and the framework verifies the signature with the application secret before trusting it. Two consequences follow. A server restart or a second instance behind a load balancer needs no session replication, because there is nothing to replicate. And whatever you put in the session travels with every request and is readable by the user, although they cannot alter it, so keep it to an identifier and look the rest up. Rotating the application secret invalidates every existing session, which is why it must come from the environment and stay stable across deployments of the same installation.
When Play is the wrong fit
A team that wants annotation-heavy MVC inside a servlet container will find Play's model foreign. Its strengths are the fast dev loop, a stateless design and built-in asynchronous support. The Play documentation has the architecture overview, and the chapter on action composition covers the API. For the servlet counterpart of this request path, see how Spring MVC handles a request.


