Demystifying Django: How I Learned the Project Structure (Through My Own Debugging Lens)

This content originally appeared on DEV Community and was authored by Zabby

Setting Up My Virtual Playground: Virtual Environments on Kali

Before diving deep into Django, I knew I needed to isolate my Python dependencies. I didn’t want one project to break another just because they used different versions of a package. So I set up a virtual environment, which felt like creating a clean slate for Django to thrive.

Here’s exactly what I did on Kali Linux:

Step 1: Installed virtualenv (if not already there) using the command

sudo apt install python3-venv

Step 2: Created a virtual environment in my project folder

python3 -m venv venv

This created a venv/ folder containing an isolated Python environment complete with its own pip, python, and site-packages.

Step 3: Activated the virtual environment

source venv/bin/activate

Once activated, my terminal prompt changed (it showed (venv)), and any packages I installed from that point forward were isolated to the project.
To deactivate it run the command: deactivate

To Install Django you run the command:

python -m pip install django

Step One: The Curious Case of the Double Folder

When I ran:

django-admin startproject my_project

I saw this structure:

my_project/
    manage.py
    my_project/
        __init__.py
        settings.py
        urls.py
        asgi.py
        wsgi.py

At first glance, the repetition felt like a mistake. But then I realized it’s deliberate:

The outer folder is your project root.
The inner folder contains your actual configuration files it’s the heart of the system. Understanding this helped me navigate imports, app registration, and even deployment configurations more confidently.

The Brains of the Operation: `settings.py` and Friends

Inside the inner my_project/ folder, I found:
settings.py: The holy grail of configuration. Middleware, installed apps, static files you name it.

urls.py: Like Django’s GPS. Every route begins here.

asgi.py and wsgi.py: I saw them as protocol translators; one for async, one for traditional web servers.

Once I edited settings.py to connect my app and saw my static files load correctly, the structure felt alive—not abstract anymore.

`manage.py`: My Swiss Army Knife

I underestimated manage.py at first. It looked like a throwaway script until I used it to:

Start the development server.
Create apps (startapp).
Run migrations.
Open the Django shell.

Now, I think of it as Django’s command-line gateway to everything project-related.

Apps: Where the Magic (Actually) Happens

When I ran:

python manage.py startapp blog

I got folders for:
models.py: My database design sandbox.
views.py: Where I learned request and response cycles the hard way.
admin.py: One of Django’s most underrated features—customizing the admin interface became a fun side mission.

Having multiple apps that plug into a single project showed me how Django scales gracefully without becoming a monolith.

Templates, Static, and Media: The Visual Layer

It finally clicked that templates aren’t just HTML they’re Django-aware, with {% %} and {{ }} blocks for logic and data. Static files gave me some CSS headaches at first, but once I correctly configured STATICFILES_DIRS, things smoothed out. And media? It’s where user uploads go. Simple, but essential for anything dynamic.

Final Thoughts
Learning Django’s project structure wasn’t just about reading docs—it was about navigating errors, debugging misconfigured paths, and rewriting what I misunderstood the first time. Now, when I open a fresh Django project, it feels less like an unknown directory tree and more like a well-organized toolkit.

If you’re just starting with Django, don’t just copy and paste. Walk through the structure, question everything, and let the architecture teach you how Django thinks.