Django Project Structure¶
Standard file hierarchy¶
my_project/ # Root directory (container for the whole project)
├── manage.py # ⚙️ Command-line orchestrator
├── my_project/ # 🛠 MAIN CONFIGURATION PACKAGE (System Level)
│ ├── __init__.py
│ ├── settings.py # 🎛 Central settings hub
│ ├── urls.py # 🔀 Main router (Root URLconf)
│ ├── asgi.py # ⚡️ Asynchronous gateway (WebSockets / Async)
│ └── wsgi.py # 🌐 Synchronous gateway (HTTP)
├── my_app/ # 📦 MODULAR APP (App Level)
│ ├── __init__.py
│ ├── admin.py # 🛡 Back-office configuration
│ ├── apps.py # 📝 App registration
│ ├── models.py # 🗄 Database schema (Data Layer)
│ ├── views.py # 🧠 HTTP orchestrator (delegates to services/selectors)
│ ├── urls.py # 🔀 App routes
│ ├── forms.py # 📋 Django Forms / ModelForms
│ ├── tests.py # ✅ Tests
│ └── migrations/ # 🕰 History of the DB's evolution
│ ├── __init__.py
│ └── 0001_initial.py
├── templates/ # 🎨 GLOBAL TEMPLATES (Presentation Layer)
│ └── base.html
└── static/ # 🖼 STATIC ASSETS
├── css/
├── js/
└── images/
Architecture and execution flow¶
High-level backend architecture¶
graph TD
Client[Browser / Client] -->|HTTP request| Nginx[Nginx Reverse proxy]
subgraph Static file serving
Nginx -->|Static/Media| Static[static/ and media/]
end
subgraph Django Application Server
Nginx -->|Dynamic traffic| Gateway[wsgi.py / asgi.py]
Gateway --> Middleware[Middleware stack]
Middleware --> Router[urls.py]
Router -->|Route match| View[views.py]
View <-->|ORM queries| Model[models.py]
View -->|Passing context| Template[templates/]
end
subgraph Data storage
Model <-->|SQL| DB[(Database)]
end
classDef step fill:#eceff1,stroke:#546e7a,stroke-width:1px;
classDef success fill:#e8f5e9,stroke:#2e7d32,stroke-width:2px;
class Client,Nginx,Static,Gateway,Middleware,Router,Model,Template,DB step;
class View success;
HTTP request lifecycle¶
sequenceDiagram
participant Nginx as Nginx
participant Web as wsgi.py / asgi.py
participant Route as urls.py
participant View as views.py
participant DB as models.py (ORM)
participant HTML as templates/
Nginx->>Web: Incoming HTTP request
Web->>Route: Handing off to the dispatcher
Route->>View: Calling the matching function
View->>DB: Book.objects.all()
DB-->>View: QuerySet (data)
View->>HTML: render(request, 'books.html', data)
HTML-->>View: Compiled HTML string
View-->>Web: HttpResponse
Web-->>Nginx: Response bytes
Detailed component breakdown¶
System level — orchestration¶
manage.py¶
| Aspect | Description |
|---|---|
| Purpose | Command-line orchestrator for the whole project |
| Internal role | Sets DJANGO_SETTINGS_MODULE and runs Django commands |
| In the request lifecycle | No part at all — does not handle live web traffic |
| In CI/CD | Runs tests, collects static files, applies migrations |
Mental model: A foreman on a construction site — you give him orders, he delegates to the framework.
Mistake: Thinking that
manage.pyruns the production server. In production this file is ignored when handling traffic.
settings.py¶
| Aspect | Description |
|---|---|
| Purpose | Central configuration hub |
| Internal role | A Python module with global variables (DB, installed apps, security keys) |
| In the request lifecycle | Loaded into memory once when the server starts |
| External services | PostgreSQL, Redis, AWS S3, Celery — all connected here |
Mental model: The main electrical panel and control board for the whole building.
# Critical settings
INSTALLED_APPS = ['django.contrib.auth', 'myapp']
DATABASES = {'default': {'ENGINE': 'django.db.backends.postgresql', ...}}
MIDDLEWARE = ['django.middleware.security.SecurityMiddleware', ...]
Mistake: Trying to change
settings.pydynamically for different users at runtime. Settings are global and static.
wsgi.py and asgi.py¶
| Aspect | Description |
|---|---|
| Purpose | Entry points for application servers (Gunicorn, Uvicorn) |
| Internal role | Provides the standard application object for talking to Django |
| In the request lifecycle | The first line of Django code when an HTTP request arrives |
wsgi.py |
Synchronous protocol — traditional HTTP requests |
asgi.py |
Asynchronous protocol — WebSockets, Server-Sent Events |
Mental model: An interpreter's desk — turns "raw" network HTTP bytes into Python dictionaries.
Mistake: Thinking that Django listens to the Internet on its own. Traffic always goes through a WSGI/ASGI server first.
App level — logic and routing¶
urls.py¶
| Aspect | Description |
|---|---|
| Purpose | URL dispatcher |
| Internal role | The urlpatterns list — maps URL strings to Python functions |
| Algorithm | Searches top to bottom, stops at the first match |
| For APIs | Defines the endpoint contract |
Mental model: A mail sorter — reads the address and hands the envelope to the right courier.
Mistake: Expecting Django to find the "best" match. It takes the first one — static routes must come before dynamic ones.
views.py¶
| Aspect | Description |
|---|---|
| Purpose | HTTP orchestrator — a thin layer between the network and the business domain |
| Internal role | Accepts an HttpRequest, calls serializer → service/selector, returns an HttpResponse |
| In the request lifecycle | Parses the request, delegates logic, formats the response |
| Can return | HTML, JSON, PDF, CSV, Redirect |
Mental model: A dispatcher — takes the call, connects it to the right specialist and passes the answer back. It decides nothing on its own.
# A view in clean architecture — as thin as possible
class FloodEventCreateAPIView(APIView):
def post(self, request):
serializer = FloodEventInputSerializer(data=request.data) # validation
serializer.is_valid(raise_exception=True)
event = flood_event_create(**serializer.validated_data) # business logic in a service
return Response(FloodEventOutputSerializer(event).data, status=201)
| A view must NOT | A view MUST |
|---|---|
| ❌ contain SQL or ORM queries | ✅ validate via an InputSerializer |
| ❌ contain business logic | ✅ call a service (mutations) |
| ❌ orchestrate transactions | ✅ call a selector (reads) |
| ❌ compute or transform data | ✅ format via an OutputSerializer |
| ❌ know about Celery tasks directly | ✅ return a Response |
Mistake in the standard architecture:
views.pyis described as the place for "business logic". In clean/production architecture, a view is only the HTTP layer. All the logic lives inservices.pyandselectors.py.
apps.py¶
| Aspect | Description |
|---|---|
| Purpose | Configuration of a specific app |
| Internal role | An AppConfig subclass — initialization when Django starts (for example, connecting Signals) |
| In the request lifecycle | No part at all — runs only once when the framework starts |
Mistake: Writing business logic or DB queries here — it will cause a failure at startup.
Data Layer¶
models.py¶
| Aspect | Description |
|---|---|
| Purpose | Defining the database schema |
| Internal role | Python classes (subclasses of models.Model) → SQL tables |
| Single source of truth | The data structure is described here — not in SQL scripts |
| In the request lifecycle | Used by views.py for reading/writing |
Mental model: The architectural blueprints of the database.
Mistake: Adding a field and thinking the DB will update itself. You need
makemigrations+migrate.
migrations/¶
| Aspect | Description |
|---|---|
| Purpose | Version control for the database schema |
| Internal role | Automatically generated Python scripts of schema changes |
| In the request lifecycle | No part at all |
| In CI/CD | The foundation of safe deployment — guarantees an identical schema on all servers |
Mental model: Git commits for DB tables — every schema change is recorded as a version.
Dangerous mistake: Deleting migration files "to keep things clean" after they have been applied — this breaks the dependency graph and synchronization with the DB.
admin.py¶
| Aspect | Description |
|---|---|
| Purpose | Configuration of the built-in admin interface |
| Internal role | Registers models on admin.site → CRUD via /admin/ |
| In the request lifecycle | Handles only requests to /admin/ paths |
| Saves | Hundreds of hours of developing internal dashboards |
Mental model: A store's back office — for trusted staff only.
Mistake: Using the admin panel as the frontend for regular customers.
Presentation Layer¶
templates/¶
| Aspect | Description |
|---|---|
| Purpose | HTML structure with dynamic data |
| Internal role | DTL (Django Template Language) — {{ variables }}, {% tags %} |
| In the request lifecycle | Called at the end of a view to generate an HTML string |
| In modern SPAs | Replaced by a JSON response if the frontend is React/Vue |
Mental model: A document form with blank fields to fill in.
Mistake: Writing full-blown Python code in templates. DTL is intentionally limited — business logic belongs in
views.py.
static/¶
| Aspect | Description |
|---|---|
| Purpose | Unchanging assets (CSS, JS, fonts, images) |
| Internal role | Sent to the client "as is", without Python processing |
| In the request lifecycle | In production it bypasses Django completely — Nginx serves it directly |
collectstatic |
Collects all static files from apps into STATIC_ROOT |
Mental model: The paint, furniture and decorations of the building.
Mistake: Expecting Django to serve static files automatically on a real server without Nginx.
How files interact during a request¶
sequenceDiagram
participant Nginx
participant Gateway as wsgi.py
participant Route as urls.py
participant View as views.py
participant DB as models.py (ORM)
participant HTML as templates/
Nginx->>Gateway: Incoming HTTP request
Gateway->>Route: Handing off to the dispatcher (Router)
Route->>View: Calling the matching View function
View->>DB: Book.objects.all()
DB-->>View: Returns a QuerySet (Data)
View->>HTML: render(request, 'books.html', data)
HTML-->>View: Returns the compiled HTML string
View-->>Gateway: HttpResponse(HTML)
Gateway-->>Nginx: Sends the bytes to the browser
Modern production architecture of a Django project¶
The standard my_project/my_app/ structure is fine for learning and small apps. Medium and large systems use a different approach — a bounded context structure.
Production project structure¶
project/
│
├── config/ ← Configuration (instead of my_project/)
│ ├── settings/ ← Split settings: base.py, local.py, prod.py
│ ├── urls.py
│ ├── asgi.py
│ └── wsgi.py
│
├── apps/ ← All business domains
│ │
│ ├── users/ ← One bounded context = one app
│ │ ├── models.py
│ │ ├── views.py
│ │ ├── urls.py
│ │ ├── services.py ← Business logic (mutations)
│ │ ├── selectors.py ← Reading data (SELECT)
│ │ ├── serializers.py ← HTTP validation + serialization
│ │ ├── permissions.py ← DRF permissions
│ │ ├── tasks.py ← Celery tasks (transport, not logic)
│ │ ├── validators.py ← Complex domain validation
│ │ ├── filters.py ← django-filter
│ │ ├── admin.py
│ │ ├── tests/
│ │ └── migrations/
│ │
│ ├── flood/ ← A separate business domain
│ ├── dem/
│ ├── ml/
│ └── papers/
│
├── shared/ ← Shared abstractions between apps
│ ├── exceptions/ ← Custom DRF exception handler
│ ├── middleware/
│ ├── auth/
│ ├── utils/
│ └── logging/
│
├── infrastructure/ ← Integrations with the outside world
│ ├── redis/
│ ├── s3/
│ ├── email/
│ ├── celery/
│ └── external_apis/
│
├── requirements/
├── docker/
├── scripts/
└── manage.py
The main rule: app = bounded context¶
An app is not a technical module but a separate business domain.
✅ Correct ❌ Wrong
apps/users/ models/ ← global for everything
apps/payments/ views/ ← global for everything
apps/flood/ utils/ ← global for everything
apps/papers/
Each app encapsulates the whole stack for its domain: models, logic, queries, serializers, tasks.
New files inside an app¶
Compared with the standard my_app/, new files appear in the production architecture:
| File | Role | Detailed documentation |
|---|---|---|
services.py |
Business logic: mutations, transactions, side effects | DJANGO_SERVICES.md |
selectors.py |
Reading data: named queries, ORM optimizations | DJANGO_SELECTORS.md |
serializers.py |
HTTP ↔ domain: InputSerializer, OutputSerializer | DJANGO_SERIALIZERS.md |
tasks.py |
Celery tasks — a transport layer, delegating to services | — |
validators.py |
Complex domain validation (validate_dem_resolution()) |
— |
permissions.py |
DRF permissions (IsOwner, IsAdminOrReadOnly) |
— |
filters.py |
django-filter FilterSet for dynamic filtering |
— |
services.py¶
# BAD — business logic in the model
class FloodEvent(models.Model):
def run_ml_pipeline(self):
...
# GOOD — business logic in a service
# services.py
def flood_event_process(*, event: FloodEvent) -> FloodEvent:
...
More details: DJANGO_SERVICES.md
selectors.py¶
# BAD — ORM right in the view, duplicated across the whole project
FloodEvent.objects.filter(is_active=True, region_id=region_id)
# GOOD — a named query in a selector
# selectors.py
def flood_events_get_for_region(*, region_id: int) -> QuerySet:
return FloodEvent.objects.filter(is_active=True, region_id=region_id)
More details: DJANGO_SELECTORS.md
tasks.py¶
# BAD — business logic in a Celery task
@shared_task
def calculate_everything(event_id):
event = FloodEvent.objects.get(id=event_id)
event.status = 'done'
event.save()
send_email(event.user.email, ...)
# GOOD — the task only transports the call into a service
@shared_task
def process_flood_task(event_id: int):
event = flood_event_get_by_id(event_id=event_id)
flood_event_process(event=event)
views.py in the production architecture¶
A view should be as thin as possible:
# A view must NOT: A view MUST:
# ❌ contain SQL ✅ validate via a serializer
# ❌ contain ML ✅ call a service
# ❌ orchestrate logic ✅ return a Response
# ❌ compute metrics
class FloodEventCreateAPIView(APIView):
def post(self, request):
serializer = FloodEventInputSerializer(data=request.data)
serializer.is_valid(raise_exception=True)
event = flood_event_create(**serializer.validated_data, created_by=request.user)
return Response(FloodEventOutputSerializer(event).data, status=201)
shared/ — shared abstractions¶
shared/ contains code used by several apps that does not belong to any specific domain.
| Folder | What's inside |
|---|---|
shared/exceptions/ |
Custom DRF exception handler (mapping DjangoValidationError → HTTP 400) |
shared/middleware/ |
Middleware for logging, correlation ID, rate limiting |
shared/auth/ |
Shared authentication logic between apps |
shared/utils/ |
Small utilities with no business domain |
shared/logging/ |
Structured logging configuration |
# shared/exceptions/handlers.py — registered once in settings.py
# and automatically catches errors in all apps
REST_FRAMEWORK = {
'EXCEPTION_HANDLER': 'shared.exceptions.handlers.custom_exception_handler',
}
infrastructure/ — integrations with the outside world¶
infrastructure/ contains adapters to external services. The key idea:
| Folder | What's inside |
|---|---|
infrastructure/redis/ |
Redis client, cache configuration |
infrastructure/s3/ |
AWS S3 / MinIO client for file storage |
infrastructure/email/ |
Email backend (SendGrid, SES) |
infrastructure/celery/ |
Celery configuration, task routing |
infrastructure/external_apis/ |
Clients for external APIs (SlideRule NASA, OpenWeather, etc.) |
# infrastructure/s3/client.py
# S3 is neither the flood domain nor the dem domain.
# It is an external storage service, isolated in infrastructure/.
class S3Client:
def upload_file(self, file_path: str, bucket: str) -> str:
...
Apps import from infrastructure, but infrastructure does not know about the apps.
Comparison: learning vs production structure¶
| Aspect | Learning (standard) | Production |
|---|---|---|
| Configuration | my_project/settings.py |
config/settings/base.py + local.py + prod.py |
| Apps | my_app/ in the root |
apps/users/, apps/flood/ |
| Business logic | In views.py |
In services.py |
| ORM queries | In views.py or models.py |
In selectors.py |
| Serialization | ModelSerializer |
InputSerializer + OutputSerializer |
| External services | Directly in views.py |
infrastructure/ |
| Shared code | utils.py in the root |
shared/ |
The learning structure is the right one for studying Django. The production structure is right when the project grows and a team works on it.