Django Project Structure0%
Django Project Structure
Beginner12 min read•Updated: Jul 11, 2026
Django Project Structure
A well-structured Django project scales cleanly from a simple prototype into an enterprise platform with dozens of engineers. Understanding the distinction between a Project and an App, as well as the responsibilities of each generated file (settings.py, urls.py, wsgi.py, asgi.py), is foundational to backend engineering.
1. Projects vs Apps: The Architectural Distinction
- Django Project: The overarching container and configuration root. It defines database connections, middleware pipelines, installed apps, global URL routing, and security settings. A project can contain multiple apps.
- Django App: A focused, self-contained Python package that accomplishes a single business domain (e.g.
users,billing,inventory,notifications). An app can theoretically be reused across different Django projects.
Output
my_enterprise_project/
├── manage.py # Project management CLI
├── config/ # Project Configuration Package
│ ├── __init__.py
│ ├── settings.py # Global project settings & configs
│ ├── urls.py # Root URL dispatcher
│ ├── asgi.py # ASGI entrypoint for WebSockets/async
│ └── wsgi.py # WSGI entrypoint for synchronous servers
└── apps/ # Custom Domain Apps
├── accounts/ # User authentication & profiles
├── billing/ # Stripe/PayPal transactions & invoices
└── products/ # Inventory & catalog models
2. Anatomy of settings.py
The settings.py file dictates all runtime behavior:
Python
import os
from pathlib import Path
# Base project directory
BASE_DIR = Path(__file__).resolve().parent.parent
# Security: Never keep SECRET_KEY or DEBUG=True in production!
SECRET_KEY = os.environ.get("DJANGO_SECRET_KEY", "dev-secret-key-change-me")
DEBUG = os.environ.get("DJANGO_DEBUG", "True") == "True"
ALLOWED_HOSTS = ["localhost", "127.0.0.1", ".enterprise.com"]
# Applications installed in this project
INSTALLED_APPS = [
# Core Django apps
"django.contrib.admin",
"django.contrib.auth",
"django.contrib.contenttypes",
"django.contrib.sessions",
"django.contrib.messages",
"django.contrib.staticfiles",
# Third-party packages
"rest_framework",
"corsheaders",
# Local domain apps
"apps.accounts",
"apps.billing",
]
# Middleware execution pipeline (order matters!)
MIDDLEWARE = [
"django.middleware.security.SecurityMiddleware",
"django.contrib.sessions.middleware.SessionMiddleware",
"corsheaders.middleware.CorsMiddleware",
"django.middleware.common.CommonMiddleware",
"django.middleware.csrf.CsrfViewMiddleware",
"django.contrib.auth.middleware.AuthenticationMiddleware",
"django.contrib.messages.middleware.MessageMiddleware",
]
# Database configuration (PostgreSQL in production, SQLite in local dev)
DATABASES = {
"default": {
"ENGINE": "django.db.backends.sqlite3",
"NAME": BASE_DIR / "db.sqlite3",
}
}
3. WSGI vs ASGI Entrypoints
wsgi.py(Web Server Gateway Interface): The synchronous Python web standard. Used by traditional production WSGI servers like Gunicorn or uWSGI to serve synchronous HTTP views.asgi.py(Asynchronous Server Gateway Interface): The modern asynchronous Python specification. Required for handling asynchronous views, WebSockets (via Django Channels), and long-lived streaming connections with servers like Uvicorn or Daphne.
4. Root URL Routing (urls.py)
The root urls.py delegates subpaths to specific apps via include():
Python
from django.contrib import admin
from django.urls import path, include
urlpatterns = [
path("admin/", admin.site.urls),
path("api/v1/auth/", include("apps.accounts.urls")),
path("api/v1/billing/", include("apps.billing.urls")),
]
Interactive Quiz
Practice Quiz
Question 1
What is the fundamental difference between a Django Project and a Django App?
Question 2
What is the purpose of asgi.py compared to wsgi.py?
Question 3
Why is DEBUG = False mandatory in production environments?
Question 4
What does the include() function do in the root urls.py?
Question 5
Why is the order of items in the MIDDLEWARE list important?
Next Lesson
Creating First Django App
Continue learning with hands-on practice, examples, and exercises in the upcoming topic.
Related Lessons
| Previous Lesson | Next Lesson |
|---|---|
| Installing Django & Environment Setup | Creating First Django App |
Practice Quiz
Test your understanding of this lesson with 5 questions. Each question has one correct answer.