Sebastian Rodrigo ARCE BRACAMONTE

Posted on May 18

Front Controller: The Pattern That Unifies Your Web Application's Entry Point

#api #architecture #backend #webdev

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

DEV Community