Part of the series: Enterprise Application Architecture Patterns — Martin Fowler
The Problem You've Probably Already Faced
You're building an API. You have /users, /products, /orders. Every endpoint needs to verify the token, log the request, handle unexpected errors. And before you know it, you end up with this:
# users.py
def handle(request):
log(request) # again
if not check_auth(request): # again
return 401
try:
# actual logic
except Exception:
return 500 # again
# products.py
def handle(request):
log(request) # again
if not check_auth(request): # again
return 401
try:
# actual logic
except Exception:
return 500 # again
Duplicated code everywhere. If tomorrow you change how authentication works, you touch 10 files. If you add rate limiting, another 10.
The Front Controller pattern solves exactly this.
What Is the Front Controller?
Fowler's definition:
"A controller that handles all requests for a Web site."
In practical terms: a single entry point that intercepts all HTTP requests, executes common logic (auth, logging, error handling), and then delegates to the appropriate handler.
This isn't a new or exotic idea. When you use Django, FastAPI, Laravel, or Spring MVC, you're already using a Front Controller. What this article does is show you what's underneath, by implementing it from scratch.
Pattern Structure
The pattern has three pieces:
HTTP Request
│
▼
┌─────────────────────┐
│ Front Controller │ ← Single entry point
│ - Logging │ Executes cross-cutting logic
│ - Authentication │
│ - Error Handling │
└──────────┬──────────┘
│
▼
┌─────────────────────┐
│ Dispatcher │ ← Maps URL → Handler
└──────────┬──────────┘
│
┌──────┴───────┐
▼ ▼
[UsersHandler] [ProductsHandler] ... ← Business logic only
Front Controller: Receives everything. Knows nothing about business, only about infrastructure.
Dispatcher: Knows which handler corresponds to which URL. Nothing more.
Handlers: Only know their own resource. They know nothing about auth or logging.
Python Implementation (No Frameworks)
The example uses only Python's standard library (http.server, json, logging). No Django, no Flask, no FastAPI. This way the pattern is fully exposed — no magic.
It simulates a store API with three resources: users, products, and orders.
Project Structure
front_controller/
├── main.py
├── front_controller.py
├── dispatcher.py
└── handlers/
├── __init__.py
├── base_handler.py
├── users_handler.py
├── products_handler.py
└── orders_handler.py
1. The Front Controller — the central piece
# front_controller.py
import logging
from http.server import BaseHTTPRequestHandler
from dispatcher import Dispatcher
VALID_TOKEN = "Bearer secret-token-123"
class FrontController(BaseHTTPRequestHandler):
dispatcher = Dispatcher()
def do_GET(self): self._handle_request("GET")
def do_POST(self): self._handle_request("POST")
def do_PUT(self): self._handle_request("PUT")
def do_DELETE(self): self._handle_request("DELETE")
def _handle_request(self, method):
self._log_request(method)
if not self._authenticate():
return
try:
self.dispatcher.dispatch(self, method, self.path)
except Exception as e:
logging.error(f"Unhandled exception: {e}")
self._send_json(500, {"error": "Internal Server Error"})
def _log_request(self, method):
logging.info(f"[{method}] {self.path}")
def _authenticate(self):
token = self.headers.get("Authorization", "")
if token != VALID_TOKEN:
self._send_json(401, {"error": "Unauthorized"})
return False
return True
def _send_json(self, status, data):
import json
body = json.dumps(data).encode()
self.send_response(status)
self.send_header("Content-Type", "application/json")
self.end_headers()
self.wfile.write(body)
def log_message(self, format, *args):
pass # Silences BaseHTTPRequestHandler's default log
Notice what this file does and what it doesn't do:
- ✅ Logs every request
- ✅ Validates the token
- ✅ Catches any unhandled exception
- ✅ Delegates to the dispatcher
- ❌ Knows nothing about users, products, or orders
2. The Dispatcher — the routing map
# dispatcher.py
from handlers.users_handler import UsersHandler
from handlers.products_handler import ProductsHandler
from handlers.orders_handler import OrdersHandler
class Dispatcher:
def __init__(self):
self.routes = {
"/users": UsersHandler(),
"/products": ProductsHandler(),
"/orders": OrdersHandler(),
}
def dispatch(self, controller, method, path):
handler = self.routes.get(path)
if handler:
handler.handle(controller, method)
else:
controller._send_json(404, {"error": f"Path '{path}' not found"})
Simple and direct. A dictionary mapping paths to handlers. If the path doesn't exist, it responds with 404. The dispatcher knows nothing about HTTP details or business logic.
3. The BaseHandler — shared behavior
# handlers/base_handler.py
import json
class BaseHandler:
def handle(self, controller, method):
if method == "GET":
self.get(controller)
elif method == "POST":
self.post(controller)
else:
self.send_error(controller, 405, "Method Not Allowed")
def get(self, controller):
self.send_error(controller, 405, "Method Not Allowed")
def post(self, controller):
self.send_error(controller, 405, "Method Not Allowed")
def send_json(self, controller, status, data):
body = json.dumps(data).encode()
controller.send_response(status)
controller.send_header("Content-Type", "application/json")
controller.end_headers()
controller.wfile.write(body)
def send_error(self, controller, status, message):
self.send_json(controller, status, {"error": message})
4. The Handlers — business logic only
# handlers/users_handler.py
from handlers.base_handler import BaseHandler
class UsersHandler(BaseHandler):
def get(self, controller):
self.send_json(controller, 200, {
"users": [
{"id": 1, "name": "Alice"},
{"id": 2, "name": "Bob"},
{"id": 3, "name": "Charlie"},
]
})
def post(self, controller):
self.send_json(controller, 201, {
"message": "User created successfully",
"resource": "/users"
})
# handlers/products_handler.py
from handlers.base_handler import BaseHandler
class ProductsHandler(BaseHandler):
def get(self, controller):
self.send_json(controller, 200, {
"products": [
{"id": 1, "name": "Laptop", "price": 999},
{"id": 2, "name": "Mouse", "price": 29},
{"id": 3, "name": "Keyboard", "price": 79},
]
})
def post(self, controller):
self.send_json(controller, 201, {
"message": "Product created successfully",
"resource": "/products"
})
# handlers/orders_handler.py
from handlers.base_handler import BaseHandler
class OrdersHandler(BaseHandler):
def get(self, controller):
self.send_json(controller, 200, {
"orders": [
{"id": 1, "user_id": 1, "total": 1028},
{"id": 2, "user_id": 2, "total": 79},
{"id": 3, "user_id": 3, "total": 29},
]
})
def post(self, controller):
self.send_json(controller, 201, {
"message": "Order created successfully",
"resource": "/orders"
})
5. The Entry Point
# main.py
import logging
from http.server import HTTPServer
from front_controller import FrontController
logging.basicConfig(
level=logging.INFO,
format="%(asctime)s [%(levelname)s] %(message)s"
)
if __name__ == "__main__":
server = HTTPServer(("localhost", 8000), FrontController)
logging.info("Server running on http://localhost:8000")
server.serve_forever()
How to Test It
Start the server:
python main.py
Successful GET — list of users:
curl -i -H "Authorization: Bearer secret-token-123" http://localhost:8000/users
Successful POST — create a product:
curl -i -X POST -H "Authorization: Bearer secret-token-123" http://localhost:8000/products
No token — 401 Unauthorized:
curl -i http://localhost:8000/users
Non-existent route — 404 Not Found:
curl -i -H "Authorization: Bearer secret-token-123" http://localhost:8000/invalid-path
Unsupported method — 405 Method Not Allowed:
curl -i -X PUT -H "Authorization: Bearer secret-token-123" http://localhost:8000/users
The Full Flow Visualized
curl GET /users (with valid token)
│
▼
FrontController.do_GET()
│
├── _log_request() → INFO [GET] /users
├── _authenticate() → token OK ✓
└── dispatcher.dispatch()
│
▼
routes["/users"] → UsersHandler
│
▼
UsersHandler.get()
│
▼
HTTP 200 {"users": [...]}
curl GET /users (no token)
│
▼
FrontController.do_GET()
│
├── _log_request() → INFO [GET] /users
└── _authenticate() → invalid token ✗
│
▼
HTTP 401 {"error": "Unauthorized"}
(never reaches the dispatcher)
What This Teaches You About Frameworks
When you use FastAPI:
app = FastAPI()
@app.middleware("http")
async def log_requests(request, call_next):
# This is the Front Controller
...
@app.get("/users")
def get_users():
# This is the Handler
...
The FastAPI app is the Front Controller. The middleware is the cross-cutting logic. The @app.get() decorators register handlers in the dispatcher. Now you know exactly what's going on under the hood.
When to Use It (and When Not To)
Use it when:
- You have cross-cutting logic (auth, logging, rate limiting) that applies to all routes
- You want a single place to change global behavior
- You're building a framework, an API Gateway, or a custom router
Don't force it when:
- Your app has 2 or 3 endpoints and won't grow
- You're already using a framework that implements it (use it, don't reinvent it)
Relationship With Other Fowler Patterns
| Pattern | Relationship |
|---|---|
| Page Controller | The opposite: each page handles its own requests. Simpler, but doesn't scale. |
| Application Controller | A natural complement: handles screen navigation and application flow, not HTTP. |
| Dispatcher View / Service to Worker | Variants of the same concept with different distribution of responsibilities. |
Conclusion
Front Controller is one of those patterns that, once you understand it, you start seeing everywhere. Spring's DispatcherServlet, Flask's app, Express's Router — they're all Front Controllers.
The value isn't in implementing it from scratch in production (that's what frameworks are for). The value is understanding the why behind its design: centralize the cross-cutting concerns, free the business logic.
When your authentication code lives in one single place, when adding new middleware means changing one line, when your handlers are so clean they only speak business — that's when the pattern is doing its job.
Full code available on GitHub: https://github.com/KrCrimson/front_controller.git