DEV Community: Wesley E. MONTCHO

The Django Digestive System: A request journey in a Django app instance.

Wesley E. MONTCHO — Sat, 28 Mar 2026 00:35:13 +0000

🇫🇷 La version française est disponible sur Hashnode : Le Système Digestif de Django : anatomie d'une requête HTTP vers Django

Before we start, let review a few words we'll keep using

Socket: ([Ref 1])

A socket is an endpoint for communication between two machines over a network. A king of pipe through which data flows. When a browser sends a request, it opens a socket connection to our server. When the server responds, it writes bytes back through that same socket.

TCP, HTTP: ([Ref 2])

TCP (Transmission Control Protocol) is the transport layer. It defines standards for handling reliable delivery of data between machines. HTTP runs on top of TCP. HTTP is just text, formatted in a specific way. A browser sends an HTTP message through a TCP connection to our server.

WSGI (Web Server Gateway Interface): ([Ref 3])

WSGI is the standard interface between a Python web application and a web server. A WSGI server ( Gunicorn, uWSGI ect ) sits between the internet and Django in our case: it accepts (manage) the TCP connection, reads the raw HTTP bytes, and calls Django with a standardized Python dictionary ( called: environ ( [Ref 4] ) and holding every thing related the to incoming request: method, path, headers, body stream ). Django never touches TCP or the raw socket directly. That boundary is WSGI's job.

Middleware: ([Ref 5])

Middleware exists in every serious web framework. Express, NestJs, Laravel , Rails ect. In Django, middleware is a layer that sits between the WSGI server and the view ( who contains our code about how we want to treat the incoming request ). Middleware can read, modify, or stop a request entirely: stopping it and returning a response immediately, without passing the request any further, is called short-circuiting.

ORM: ([Ref 6])

ORM stands for Object-Relational Mapper. It's the layer that translates between Python objects and database tables. Rails calls it ActiveRecord, Laravel calls it Eloquent: in Django it's just "the ORM.".

Still here? Good 👌. So now that we have a clear view about these words, Let's trace a request. 🗺️

1. Before Django, Raw Bytes comming from a client

A browser decides to call our API. It opens a socket [Ref 1] connection to our server and sends something like this, which is a typical http text format:

GET /users/42/ HTTP/1.1
Host: api.example.com
Authorization: Bearer eyJhbG...
Accept: application/json
...
...
...

That's it. Plain text. For now, no Python, no Django, no objects. A formatted string traveling through the socket [Ref 1], controlled by the TCP [Ref 2] standard.

The WSGI server [Ref 3] receives this on the socket, parses the HTTP text, and builds the environ dict [Ref 4]. Then it calls Django. That is where our story picks up.

2. The Birth of `HttpRequest`

The entry point of every Django request is WSGIHandler.__call__(), defined in django/core/handlers/wsgi.py.

This is the exact line where the request stops being a dictionary and becomes a Python object:

# django/core/handlers/wsgi.py (simplified)
class WSGIHandler(base.BaseHandler):
    def __call__(self, environ, start_response):
        request = self.request_class(environ)  # ← born here
        response = self.get_response(request)
        # ...

self.request_class is HttpRequest class. Django takes the raw environ dict and wraps it into a rich, usable Python object.

Here is what that transformation looks like:

Notice request.META always contains the full environ dict. Nothing is lost. It is just made accessible through a proper Python interface.

Are we following? Good 👌. HttpRequest is alive. Now it has to travel.

3. The Middleware flow [Ref 5]

This is where most people have a fuzzy mental model, and it's worth clearing up.

Middlewares flow is not a pipeline where each step ( middleware ) independently processes the request and passes it along. It's a stack of nested wrappers. Each middleware wraps arounFork in thed everything that comes after it.

Here is what a middleware actually looks like:

class OurExampleMiddleware:
    def __init__(self, get_response):
        self.get_response = get_response  # the next layer

    def __call__(self, request):
        # → this runs before the view
        do_something_with(request)

        response = self.get_response(request)  # call the next layer. 
        # So if we have n other layer before the view, 
        # all them will be executed, the view too, 
        # before we continue to the next instruction of the current method

        # ← The, this runs after the view, on the way back out
        do_something_with(response)

        return response

Middlewares are like, chained. So, self.get_response is the next middleware in the chain () or the view itself if we are at the last middleware). Calling it sends the request deeper. Not calling it and returning a response. If a middleware return a response that way, directly is a short-circuit and the view never runs.

Django processes MIDDLEWARE top to bottom on the way in, bottom to top on the way back. Order is not optional.

Here is what the built-in middleware injects as the request travels through:

In a sense, and compared to the human digestive system, This is the intestinal tract of the request. Each layer absorbs one thing: session here, user identity there etc. and passes the rest along. By the time the request exits, it's been fully enriched. Short-circuiting? That's your body rejecting something before it reaches the bloodstream.
By the time the request reaches our view ( officially the bloodstream 😅 ), request.session and request.user are already there, added by related middleware. Not magic just, middleware flow doing its job quietly.

4. URL Routing: The Crossroads

HttpRequest has cleared the middleware stack. Django now needs to figure out which view should handle it.

URLResolver walks urlpatterns (the list we define in urls.py in the core folder containing settings), comparing the request path against each pattern. The first match wins. Captured groups become kwargs.

# urls.py
path("users/<int:pk>/", UserDetailView.as_view()),

# request to /users/42/ → kwargs = {"pk": 42}

If nothing matches, Django returns a 404 before our view code ever runs. At this step, no view, no serializer, no database. Just a 404 out.

Still with us? We're almost at the part where our code actually runs.

5. Our Code Finally Runs 💻

The view receives two things: the HttpRequest object and the resolved kwargs. Everything that happened before this (socket, WSGI, environ, middleware, routing ) was Django's machinery. This part is ours.

class UserDetailView(RetrieveAPIView):
    def get(self, request, pk):
        # request.user is already set ( thank AuthenticationMiddleware, during the middleware flow )
        # pk came from the URL thank URLResolver
        user = User.objects.get(pk=pk)
        return Response(UserSerializer(user).data)

s
User.objects.get(pk=pk): this is where the ORM [Ref 6] steps in. Django translates this Python call into a SQL query, hits the database, and returns a Python object. One line from us; a lot happening underneath. [I tried to read this code in the django module in the past, and it was not a simple logics. Thanks to django contributors.]

For those of us using Django REST Framework: APIView.dispatch() ( The base of viewsets ect. ) adds one more execution layer before our .get() or .post(), or .create() or custom action view runs: authentication classes, permission classes, throttle classes. We'll go deep on this in a dedicated post. For now, just know it's there.

6. The Return Journey

Our view returns an HttpResponse. This is where the middleware stack unwinds.

The same chain runs in reverse: bottom to top. Each middleware's post-view logic executes as get_response(request) returns back up the call stack.

Headers like Content-Security-Policy, Strict-Transport-Security, and Set-Cookie are added on this return trip. The middleware that sits at the top of MIDDLEWARE is the last to touch the response. That's the nesting in action.

7. Out the Other End

WSGIHandler takes the HttpResponse object returned and then converts it back to bytes, according to the HTTP protocol

The client receives HTTP text:

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 87
Set-Cookie: sessionid=abc123; HttpOnly; Path=/
...
...
...

{"id": 42, "name": "..."}

Full circle. Bytes in, bytes out. Everything in between was Django. Digestion complete.

That's the full trip

Most of us live in section 5. The view, the serializer, the business logic. That's where the product lives: that's normal.

But the next time request.user is an AnonymousUser we didn't expect, or a response header is missing, or a 404 shows up before our code even has a chance to run, we'll know exactly which layer to look at.

The machinery is not magic. It's layers, each doing one job, in a specific order. Knowing this also helps us customize some behavior, if required by our business logic.

Which layer have we had to dig into when debugging? Drop it in the comments.

Structuring a Django REST Framework API Project: How Do I Go About It?

Wesley E. MONTCHO — Mon, 23 Mar 2026 00:33:55 +0000

This is my first technical blog post. More will follow on Django, architecture, and things I learned accross years. Discussions and comments are very welcome.

A few weeks ago, a senior Django developer (more experienced than me 😅) joined a project I had been building solo. After reviewing the codebase, he sent me this message (translated and paraphrased from French):

"There are quite a few things that are not well finished. Some deficiencies. But there are also some very beautiful things that allowed me to move fast."

That last sentence is why I told myself: why not start writing, both to preserve what worked and to connect with others? So here I am. 👋

Properly structuring a project, especially a large one, is crucial. It's about making decisions early that let you, and others, navigate confidently, add features safely, and hand the project off without needing to be called back every five minutes.

Let's get into it. 🚀

The Problem With Django's Default Layout

When you run django-admin startproject backend, you get this:

backend/
├── backend/
│   ├── settings.py
│   ├── urls.py
│   ├── wsgi.py
│   └── asgi.py
├── manage.py

Then you add your first app:

python manage.py startapp myapp

And suddenly:

backend/
├── myapp/
│   ├── models.py
│   ├── views.py
│   ├── admin.py
│   └── tests.py
├── backend/
│   └── settings.py

This works perfectly. For a tutorial. 😬

In a real production context, models.py quickly hits 1,000+ lines. views.py become too long for reading. settings.py mixes database config, email config, AWS config, etc.

So, to ensure proper scaling as the app grow, it becom natural to: design our app from day one.

Let's jump on that.

1. The Top-Level Split: `apps/` and `backend/`

The first and most impactful decision: separate your Django apps from your project configuration.

my-project/
├── backend/           ← Django project config (settings, urls, celery…)
├── apps/              ← All your Django apps live here
├── docs/              ← Documentation
├── scripts/           ← Utility scripts
├── tests/             ← Test suite
├── manage.py
└── requirements.txt

Any developer opening this repo for the first time immediately understands the map:

backend/ → framework config, don't touch without a reason
apps/ → this is where the features and business logics are implemented

That is simple, obvious with no ambiguity. That's the goal.

2. The `backend/` Folder: Config That Breathes

Still with me? Good. 👌

The most common mistake inside backend/ is keeping a single monolithic settings.py. The settings.py is where django settings, third parti apps settings live. So JWT, email, AWS, rate limiting: all in one file becomes a lot of config with no real structure as the app grow.

Split settings by domain:

backend/
├── settings/
│   ├── __init__.py      ← Loads sub-modules
│   ├── base.py          ← Core Django config (installed apps, middleware, DB…)
│   ├── smtp.py          ← Email config only
│   ├── ...
│   └── configs/
│       └── storages.py  ← S3/media storage config
├── urls.py              ← Root URL dispatcher
├── celery.py            ← Celery app init (if using async tasks)
├── asgi.py
└── wsgi.py

# backend/settings/smtp.py: email concerns only
EMAIL_BACKEND = "django.core.mail.backends.smtp.EmailBackend"
EMAIL_HOST = os.environ.get("EMAIL_HOST")
EMAIL_PORT = int(os.environ.get("EMAIL_PORT", 587))
EMAIL_USE_TLS = True

# backend/settings/configs/storages.py: storage concerns only
DEFAULT_FILE_STORAGE = "storages.backends.s3boto3.S3Boto3Storage"
AWS_STORAGE_BUCKET_NAME = os.environ.get("AWS_BUCKET_NAME")

When a DevOps engineer needs to update email config, they go directly to smtp.py. They don't have to read 400 lines of unrelated settings. This is respect for the next developer's time. 🙏

3. The `apps/` Folder: One Domain, One App

Every feature domain gets its own Django app. No monolithic core/ app that holds everything.

apps/
├── authentication/    ← Registration, login, JWT…
├── transactions/      ← Transactions, refunds…
├── users/             ← User model, profiles…
├── notifications/     ← Email, SMS, Push, WhatsApp…
├── marketing/         ← Referrals, contact messages…
├── settings/          ← System and per-user settings
└── utils/             ← Shared code (base model, enums, errors, middleware)

Each app is a bounded context: it owns its models, its views, its serializers, its business logic. If tomorrow you extract notifications/ into a separate microservice, the limits are already drawn.

The rule I apply: if you can describe it in one domain noun, it's an app. Authentication, Transactions, Notifications. Not Stuff, not Core, not Api.

4. Inside an App: Every File Has a Job

Still following? 👀 This is where most Django projects diverge from best practices.

The generated models.py / views.py monolith pattern appear to not ease scaling. Here's what a well-structured app looks like instead:

apps/transactions/
├── models/
│   ├── __init__.py          ← Star-imports all model files
│   ├── transactions.py
│   ├── refunds.py
│   └── …
├── serializers/
│   ├── transactions.py
│   ├── refunds.py
│   └── …
├── views/
│   ├── transactions.py
│   ├── refunds.py
│   └── …
├── services/
│   ├── transaction_processor.py
│   └── refund_service.py
├── admin/
│   ├── __init__.py
│   └── transactions.py
├── router.py
├── urls.py
├── tasks.py     ← Celery tasks (can be split too)
├── apps.py
└── tests.py

Split models into sub-files

The models/__init__.py re-exports everything via star imports:

# apps/transactions/models/__init__.py
from apps.transactions.models.transactions import *
from apps.transactions.models.refunds import *

From Django's perspective, nothing changes: apps.transactions.Transaction still works. From a developer's perspective, everything changes:

Each model file stays focused and readable (< 300 lines)
Git merge conflicts are rare and simple to resolve when they happen
Searching "transactions" in your file list returns models, services, serializers, all at once

The `services/` layer

Views should not contain business logic. This isn't a rule I invented. It's a principle that saves you every time you need to reuse logic in a task, a management command, or a test.

# ❌ Business logic in the view — classic antipattern
class TransactionViewSet(ModelViewSet):
    def create(self, request):
        dest_user = User.objects.get(...)
        if not dest_user.is_active:
            raise ValidationError("User not available")
        # ...50 more lines of business logic...

# ✅ The view delegates to a service
class TransactionViewSet(ModelViewSet):
    def create(self, request):
        serializer = CreateTransactionSerializer(data=request.data)
        serializer.is_valid(raise_exception=True)
        transaction = TransactionProcessor.create_transaction(
            user=request.user,
            **serializer.validated_data
        )
        return Response(TransactionSerializer(transaction).data)

TransactionProcessor.create_transaction() can now be called from a view, a task, a test, or a management command, without changing a single line. 💪

5. The Base Model: Your Foundation for Every Table

Every model in this project inherits from one class. Just one.

# apps/utils/models/base_model.py
from uuid import uuid4
from django.db import models
from django_softdelete.models import SoftDeleteModel

class AbstractCommonBaseModel(SoftDeleteModel):
    uuid = models.UUIDField(primary_key=True, default=uuid4, editable=False)
    active = models.BooleanField(default=True)
    timestamp = models.DateTimeField(auto_now_add=True)
    updated = models.DateTimeField(auto_now=True)

    class Meta:
        abstract = True

Every model then uses it:

from apps.utils.models.base_model import AbstractCommonBaseModel

class Transaction(AbstractCommonBaseModel):
    # uuid, active, timestamp, updated → already there for free
    status = models.CharField(...)
    amount = models.DecimalField(...)

Pure DRY. You get for free, on every table:

Field	Benefit
`uuid` (PK)	No sequential IDs leaking record counts; safe in URLs
`active`	Logical on/off switch
`timestamp`	Creation date, always available
`updated`	Last modification date, always available
Soft delete	`.delete()` marks the row deleted, doesn't destroy it

Soft delete, specifically, has become a habit over the years. You never permanently remove a sensitive record. Even if a user "deletes" something from their view, the row stays for audits, disputes, and reconciliation. 🔍

Defining this in the base model means you can never forget it. The pattern is enforced at the class hierarchy level.

6. The `utils/` App: Your Project's Internal Library

Every project accumulates shared code. The question is whether it lives scattered everywhere or in one dedicated place.

apps/utils/
├── models/
│   └── base_model.py           ← AbstractCommonBaseModel
├── xlib/                       ← "extended library" (your project's vocabulary)
│   ├── enums/
│   │   ├── base.py             ← BaseEnum
│   │   ├── errors.py           ← All error codes
│   │   ├── transactions.py     ← TransactionStatusEnum, etc.
│   │   └── users.py            ← UserStatusEnum, etc.
│   ├── error_util.py           ← Centralized error resolution
│   ├── exceptions.py           ← Custom domain exceptions
│   └── validators.py           ← Custom validators
├── middleware/
│   └── …
├── commons/
│   └── mixins.py               ← Reusable ViewSet mixins
└── views/
    └── errors.py               ← Public error map endpoint

One pattern worth highlighting: the Enum system. Instead of scattering verbose choice tuples across model files:

# ❌ The old way, repeated everywhere
status = models.CharField(choices=[('PENDING', 'Pending'), ('FAILED', 'Failed'), ...])

# ✅ One enum, reused everywhere
from apps.utils.xlib.enums import TransactionStatusEnum

status = models.CharField(
    choices=TransactionStatusEnum.items(),
    default=TransactionStatusEnum.PENDING.value,
)

One source of truth. No copy-paste drift, no Model.BLABLABLA. 🎯

7. URL Routing: Three Layers, Clear Contracts

Every app follows the same three-layer URL pattern. No exceptions.

Layer 1 (router.py): Register ViewSets

# apps/transactions/router.py
from rest_framework.routers import DefaultRouter
from apps.transactions.views import TransactionViewSet, RefundViewSet

router = DefaultRouter()
router.register(r'refunds', RefundViewSet, basename='refunds')
router.register(r'', TransactionViewSet, basename='transactions')

urls_patterns = router.urls

Layer 2 (urls.py): App URL contract (router URLs + any manual path() entries)

# apps/transactions/urls.py
from apps.transactions.router import urls_patterns

urlpatterns = urls_patterns

Layer 3 (backend/urls.py): Root dispatcher, versioned

urlpatterns = [
    path("v1/auth/",          include("apps.authentication.urls")),
    path("v1/transactions/",  include("apps.transactions.urls")),
    path("v1/users/",         include("apps.users.urls")),
    # …
]

A new developer looking for "where does the transaction list endpoint come from" follows this path in under 60 seconds. No magic. No hunting. 🗺️

When you need /v2/, you add a second block without touching the first.

Bonus: `scripts/` and `docs/`

Small things that signal a professional codebase:

scripts/
├── rmpycaches.py        ← Clear all __pycache__ folders
└── rmmigrationfiles.py  ← Remove migration files (for dev resets)

docs/
├── modelings/           ← (For example ) Use cases, class diagrams, sequence diagrams

The Real Impact

We're almost done, and this last part is the reason any of this matters. 🏁

The senior developer who reviewed my codebase moved fast. He could navigate without asking me where things were. That's the metric that matters: not "is the code clever" but "can the next person read it?"

During development:

You never wonder "where should I put this?". The structure answers.
Features are isolated: adding marketing/ doesn't touch transactions/
The base model prevents forgotten patterns (timestamps, soft delete)

During code review:

PRs stay small because changes live in one app's files
Reviewers know exactly where to look

During onboarding:

A new developer maps the codebase in 20 minutes by reading folder names
backend/urls.py is the full table of contents for the API

During incidents:

Bug in transaction creation? Check services/transaction_processor.py, not a 1,000-line views.py

During refactoring:

Extracting notifications/ into a microservice means moving one folder, not grepping scattered code

There are so many other small tips (😅) i used to use when it come to prepare my api for scaling, i will try to talk about them in my next posts.

So, now, to resume: The takeaway Checklist

For your next Django project, or to refactor your current one:

[ ] Name your config folder backend/ (or config/), not after your project
[ ] Put all apps under apps/
[ ] Split settings.py by domain: smtp.py, storages.py, etc.
[ ] Create AbstractCommonBaseModel with UUID PK, timestamps, and soft delete
[ ] Split models.py into models/<domain>.py files, re-exported via __init__.py
[ ] Add a services/ layer: views call services, not raw ORM
[ ] Create apps/utils/ as your project's internal library
[ ] Use enums for model choices (one source of truth)
[ ] Follow the three-layer URL pattern: router.py → urls.py → backend/urls.py
[ ] Add a scripts/ folder for repetitive dev commands
[ ] Write at least a minimal docs/. Your future self will thank you.

What's Next

Next post: Standardized error handling in Django REST Framework, with i18n support and a React integration example.

Every API returns errors. The question is whether they're consistent, translatable, and useful to the frontend consuming them. I'll show you the ErrorEnum + ERROR_MAP pattern, how drf-standardized-errors shapes every response, and how to wire it up so a React app displays the right message in the right language, without any if/else chains.

If you remark something I got wrong, or if you do it differently and it works better, comment below. I'm here to learn as much as to share. 🤝