🎸 Django Framework Architecture

What Is Django?

Django is a high-level Python web framework that encourages rapid development and clean, pragmatic design. It was built in 2003–2005 inside the newsroom of the Lawrence Journal-World, where developers needed to ship database-backed features on deadline — and it was named after jazz guitarist Django Reinhardt. That origin story explains its whole personality: opinionated, complete, and fast to build with.

Django's defining trait is that it is "batteries-included." Where a micro-framework hands you a bare request/response loop and asks you to assemble the rest, Django ships with an ORM, an authentication system, an auto-generated admin site, form handling, security middleware, and a template engine — all in the box, all designed to work together.

🎸 The orchestra analogy: Think of Django as a well-rehearsed orchestra. The ORM section handles data, templates play the visuals, the URL dispatcher conducts routing, and the security middleware keeps everyone in time. You don't hire each musician separately — the ensemble arrives ready to perform, and your job is to choose the piece.

What makes Django worth learning:

• Security by default — protection against SQL injection, XSS, CSRF, and clickjacking is built in.
• Proven scale — Instagram, Spotify, Pinterest, and Disqus all run Django in production.
• The admin site — a full data-management interface generated from your models, free.
• Excellent documentation — widely regarded as some of the best in open source.

The MVT Architecture

Django organizes code with a pattern it calls Model-View-Template (MVT). It is a close cousin of the classic Model-View-Controller (MVC) pattern, but the names are shuffled in a way that trips up newcomers coming from Rails or Laravel.

Here is how the four pieces cooperate to serve a single page — say, a blog post at /blog/post/123/:

The MVT flow: the URLconf routes to a view, the view talks to models, and a template turns the data into HTML.

Django vs. Flask vs. FastAPI

Django is one of three Python frameworks you'll meet constantly. They embody different philosophies, and knowing where each shines is a genuinely useful skill.

Roughly speaking, Django sits between Flask's "assemble-it-yourself" minimalism and the strict conventions of Rails. It gives you a comprehensive toolkit but stays flexible about how you use it.

The Request-Response Cycle

Every request that reaches a Django app travels through a fixed pipeline. Understanding the order of stages is the single most useful mental model for debugging — when something goes wrong, you can reason about where in the pipeline it happened.

1. WSGI/ASGI server (Gunicorn or Uvicorn) receives the raw request and hands it to Django.
2. The request passes down through middleware — security checks, session loading, authentication.
3. The URL resolver matches the path to a view.
4. The view runs your logic, usually querying models.
5. A template renders the response HTML (or a JSON serializer builds a response).
6. The response travels back up through middleware — where headers, compression, and cookies are applied.
7. The finished HTTP response returns to the client.

Middleware: hooks around every request

Middleware is a stack of components that wrap the view. Each one can inspect or modify the request on the way in and the response on the way out. Django ships with several essential ones — SecurityMiddleware, SessionMiddleware, AuthenticationMiddleware, and CsrfViewMiddleware among them.

Writing your own is straightforward — here is one that logs how long each request takes:

import time
import logging

logger = logging.getLogger(__name__)

class TimingMiddleware:
    def __init__(self, get_response):
        # Runs once when the server starts
        self.get_response = get_response

    def __call__(self, request):
        start = time.perf_counter()

        # Hand off to the next middleware or the view
        response = self.get_response(request)

        duration_ms = (time.perf_counter() - start) * 1000
        logger.info("%s %s -> %s (%.1f ms)",
                    request.method, request.path,
                    response.status_code, duration_ms)
        return response

You activate it by adding its dotted path to the MIDDLEWARE list in settings. Order matters: middleware runs top-to-bottom for requests and bottom-to-top for responses, so a component you want to run "first on the way in, last on the way out" belongs near the top.

WSGI vs. ASGI

Django historically spoke WSGI (synchronous). Modern Django also supports ASGI (asynchronous), which unlocks async views, WebSockets, and long-lived connections. A new project generated with Django 5 includes both wsgi.py and asgi.py, so you can choose your deployment path later.

Projects, Apps & Structure

Django draws a sharp line between two concepts, and getting them straight early saves a lot of confusion:

• A project is the whole web application — its settings, its URL root, and the collection of apps it runs.
• An app is a self-contained, ideally reusable module that does one job — a blog, a shop, an accounts system.

A project contains many apps; a well-designed app could be dropped into a different project. Here is the layout a fresh Django 5 project produces:

myproject/                  # Project root (the "repository")
├── manage.py               # Command-line entry point
│
├── myproject/              # The project package (config lives here)
│   ├── __init__.py
│   ├── settings.py         # Configuration
│   ├── urls.py             # Root URL routing
│   ├── asgi.py             # Async server entry point
│   └── wsgi.py             # Sync server entry point
│
├── blog/                   # An app
│   ├── __init__.py
│   ├── admin.py            # Admin site registration
│   ├── apps.py             # App configuration
│   ├── migrations/         # Database schema history
│   ├── models.py           # Data models
│   ├── tests.py            # Tests
│   ├── urls.py             # App-level URL routing (you create this)
│   └── views.py            # Views
│
└── templates/              # Shared templates

The two commands that create these are:

# Create the project skeleton
django-admin startproject myproject .

# Create an app inside it
python manage.py startapp blog

Splitting a project into apps

Modularity is Django's superpower. A real e-commerce project might divide its concerns like this:

Settings & Configuration

A Django project's behavior is driven by settings.py. A few settings appear in nearly every project:

# myproject/settings.py
from pathlib import Path
import os

BASE_DIR = Path(__file__).resolve().parent.parent

# Every app you use must be listed here
INSTALLED_APPS = [
    "django.contrib.admin",
    "django.contrib.auth",
    "django.contrib.contenttypes",
    "django.contrib.sessions",
    "django.contrib.messages",
    "django.contrib.staticfiles",
    "blog",            # your own apps
]

MIDDLEWARE = [
    "django.middleware.security.SecurityMiddleware",
    "django.contrib.sessions.middleware.SessionMiddleware",
    "django.middleware.common.CommonMiddleware",
    "django.middleware.csrf.CsrfViewMiddleware",
    "django.contrib.auth.middleware.AuthenticationMiddleware",
    "django.contrib.messages.middleware.MessageMiddleware",
    "django.middleware.clickjacking.XFrameOptionsMiddleware",
]

DATABASES = {
    "default": {
        "ENGINE": "django.db.backends.postgresql",
        "NAME": os.environ["DB_NAME"],
        "USER": os.environ["DB_USER"],
        "PASSWORD": os.environ["DB_PASSWORD"],
        "HOST": os.environ.get("DB_HOST", "127.0.0.1"),
        "PORT": os.environ.get("DB_PORT", "5432"),
    }
}

Never hard-code secrets

Notice that the database credentials above come from environment variables, not literal strings. The same rule applies to the SECRET_KEY and the DEBUG flag. Committing these to version control is one of the most common — and most dangerous — beginner mistakes.

# Read secrets from the environment, with safe defaults
SECRET_KEY = os.environ["DJANGO_SECRET_KEY"]

# DEBUG must be False in production
DEBUG = os.environ.get("DJANGO_DEBUG", "False") == "True"

ALLOWED_HOSTS = os.environ.get("DJANGO_ALLOWED_HOSTS", "").split(",")

# Harden HTTPS in production
if not DEBUG:
    SECURE_SSL_REDIRECT = True
    SESSION_COOKIE_SECURE = True
    CSRF_COOKIE_SECURE = True
    SECURE_HSTS_SECONDS = 31_536_000  # one year

For anything beyond a toy project, split settings by environment. A common layout replaces settings.py with a package:

myproject/settings/
├── __init__.py
├── base.py          # Shared settings
├── development.py   # DEBUG=True, local database
└── production.py    # DEBUG=False, hardened security

You then point Django at the right one with an environment variable, so the same codebase behaves correctly everywhere:

# manage.py / wsgi.py
os.environ.setdefault(
    "DJANGO_SETTINGS_MODULE",
    "myproject.settings.production",
)

Hands-on: Scaffold a Project

# pages/views.py
from django.http import HttpResponse

def home(request):
    return HttpResponse("<h1>Hello from Django!</h1>")

# pages/urls.py  (create this file)
from django.urls import path
from . import views

urlpatterns = [
    path("", views.home, name="home"),
]

# myproject/urls.py
from django.contrib import admin
from django.urls import path, include

urlpatterns = [
    path("admin/", admin.site.urls),
    path("", include("pages.urls")),
]

python manage.py migrate      # set up the built-in tables
python manage.py runserver

Best Practices

Summary & Quiz

📚 Further Reading

• Django docs — Overview & philosophy
• Django docs — Middleware
• Django docs — Settings reference

🚀 What's Next?

Now that you can see the whole machine, we'll zoom into its heart. In the next lesson, Data Modeling in Django, you'll define models, choose field types, wire up relationships, and let migrations build your database schema.