Systems

Django's source tree is organised as a set of cooperating subsystems under the top-level django/ package. Each subsystem owns its own directory, has a clear public surface, and is loosely coupled to its neighbours. This section documents each one.

What lives where

Subsystem	Source root	One-line description
ORM	django/db/	Models, querysets, expressions, transactions, and the database backends
Migrations	django/db/migrations/	Schema migration generation, graph resolution, and execution
HTTP	django/http/, django/core/handlers/	HttpRequest, HttpResponse, multipart parsing, WSGI/ASGI handlers
URL routing	django/urls/	URL resolution, reverse lookup, namespacing
Views	django/views/	Function- and class-based view machinery, debug page, error views
Templates	django/template/	The Django template language, default tags/filters, pluggable backends
Forms	django/forms/	Form fields, widgets, formsets, and ModelForm
Middleware	django/middleware/	Built-in middleware (CSRF, common, cache, locale, security, gzip, CSP)
Management commands	django/core/management/	manage.py / django-admin, the command runner, built-in commands
Apps and settings	django/apps/, django/conf/	The app registry and the lazy settings object
Signals and dispatch	django/dispatch/, django/core/signals.py	In-process pub/sub used across the framework
Core utilities	django/core/, django/utils/	Cache, mail, signing, validators, system checks, encoding, autoreload
Test framework	django/test/	TestCase, the test client, the test runner
Contrib apps	django/contrib/	Optional batteries: admin, auth, sessions, messages, gis, postgres, etc.

How they fit together

The architecture page has the canonical diagram. Two patterns are worth flagging here:

• Settings-driven configuration: every subsystem reads from django.conf.settings rather than from constructor arguments. This keeps the public API surface small but means almost everything has an implicit dependency on django/conf/__init__.py.
• App-registry-driven discovery: the ORM, the admin, migrations, the contenttypes app, and many checks ask the registry for "all installed apps" or "all models" rather than walking imports themselves. This makes installed apps composable — adding an entry to INSTALLED_APPS is the only configuration step.

If you're new to a subsystem, the overview/architecture.md page explains the request-and-response flow that ties them together. From there, drill into the subsystem-specific page below.

Conventions across pages

Each page in this section is structured the same way:

1. Purpose — what the subsystem does in 2-3 sentences.
2. Directory layout — the files and folders, with one-line descriptions.
3. Key abstractions — a table of the most important types.
4. How it works — the main control flow, with a Mermaid diagram when it helps.
5. Integration points — what depends on this subsystem and what it depends on.
6. Entry points for modification — where to start reading if you need to change something.
7. Key source files — pointer table to the heaviest files.