Django project structure walkthrough - Deep Dive

Overview - Django project structure walkthrough

What is it?

Django project structure is the organized layout of files and folders that Django creates when you start a new project. It includes settings, apps, and configuration files that help your web application work smoothly. This structure helps you keep your code clean and easy to manage. It is designed to separate different parts of your project logically.

Why it matters

Without a clear project structure, your code would be messy and hard to maintain, especially as your app grows. Django's structure solves this by giving you a ready-made organization that helps you find and fix problems quickly. It also makes it easier for teams to work together because everyone knows where to put and find things. Without it, building complex web apps would be much slower and more error-prone.

Where it fits

Before learning Django project structure, you should understand basic Python and how web apps work. After this, you can learn how to create apps inside the project, connect databases, and build views and templates. This structure is the foundation that supports all Django development tasks.

Mental Model

Core Idea

Django project structure is like a well-organized toolbox where each folder and file has a clear role to keep your web app running smoothly and easy to build upon.

Think of it like...

Imagine building a house: the project structure is like the blueprint and the organized rooms where each room has a specific purpose, like the kitchen for cooking and the bedroom for sleeping. This helps everyone know where things belong and how to find them.

DjangoProject/          ┌─────────────┐
├── manage.py           │  manage.py  │  # Command-line utility to run tasks
├── DjangoProject/      ├─────────────┤
│   ├── __init__.py    │  Settings   │  # Configuration for the project
│   ├── settings.py    │  URLs       │  # URL routing for the project
│   ├── urls.py        │  WSGI       │  # Entry point for web servers
│   └── wsgi.py        └─────────────┘
├── app1/              # Your first app folder
│   ├── migrations/    # Database migrations
│   ├── __init__.py    # Marks this as a Python package
│   ├── admin.py       # Admin site configuration
│   ├── apps.py        # App configuration
│   ├── models.py      # Data models
│   ├── tests.py       # Tests for this app
│   └── views.py       # Logic for handling requests
└── templates/         # HTML templates for rendering pages

Build-Up - 7 Steps

1

Foundation

Understanding manage.py role

Concept: Learn what manage.py does and why it is important.

manage.py is a command-line tool automatically created by Django. It helps you run your project, start apps, apply database changes, and more. Think of it as the remote control for your Django project. You use it to tell Django what to do.

Result

You can run commands like 'python manage.py runserver' to start your web app locally.

Knowing manage.py is your main control point helps you understand how to interact with your Django project from the terminal.

2

Foundation

Exploring the project folder

Concept: Identify the main project folder and its key files.

Inside your Django project folder (named after your project), you find settings.py, urls.py, wsgi.py, and __init__.py. settings.py holds all configuration like database info and installed apps. urls.py maps web addresses to code. wsgi.py connects your app to web servers. __init__.py marks this folder as a Python package.

Result

You understand where to configure your app and how URLs are handled.

Recognizing these files as the project's backbone clarifies where to make global changes.

3

Intermediate

Apps: building blocks inside projects

🤔Before reading on: do you think apps are optional or required parts of a Django project? Commit to your answer.

Concept: Apps are smaller parts inside a project that handle specific features.

A Django project can have many apps, each responsible for a part of the website, like a blog or user accounts. Each app has its own folder with models.py, views.py, admin.py, and migrations. This separation helps keep code organized and reusable.

Result

You can create multiple apps to add features without mixing code.

Understanding apps as modular pieces helps you build scalable and maintainable projects.

4

Intermediate

Templates and static files explained

🤔Before reading on: do you think templates are Python code or HTML files? Commit to your answer.

Concept: Templates hold HTML files that define how pages look, separate from Python code.

Templates are stored in a folder named 'templates'. They use Django's template language to insert dynamic content. Static files like CSS, JavaScript, and images live in a 'static' folder. Separating these keeps design and logic apart.

Result

You can change how your site looks without touching Python code.

Separating templates and static files from code improves collaboration between developers and designers.

5

Intermediate

Migrations: tracking database changes

🤔Before reading on: do you think migrations change your database automatically or just prepare instructions? Commit to your answer.

Concept: Migrations are files that record changes to your database schema.

When you change models.py, Django creates migration files inside the migrations folder. These files tell Django how to update the database safely. You apply them with 'python manage.py migrate'. This system prevents data loss and keeps your database in sync with your code.

Result

You can evolve your database structure without manual SQL commands.

Knowing migrations protect your data and automate updates is key to managing databases confidently.

6

Advanced

Settings.py: configuration central

🤔Before reading on: do you think settings.py is safe to share publicly or contains sensitive info? Commit to your answer.

Concept: settings.py controls all important configurations, including secret keys and database connections.

This file includes security keys, debug mode, allowed hosts, installed apps, middleware, and database settings. It is critical to keep secret keys private and configure debug mode properly for development vs production. You can split settings into multiple files for better management.

Result

You can customize your project environment securely and flexibly.

Understanding the power and risks in settings.py helps prevent security mistakes and eases deployment.

7

Expert

WSGI and ASGI: web server gateways

🤔Before reading on: do you think wsgi.py runs your app or just connects it to servers? Commit to your answer.

Concept: wsgi.py and asgi.py are entry points that connect your Django app to web servers.

WSGI (Web Server Gateway Interface) is a standard Python interface for synchronous web apps. ASGI (Asynchronous Server Gateway Interface) supports async features and websockets. These files expose your app to servers like Gunicorn or Daphne. They do not run your app logic but serve as bridges.

Result

You understand how your app communicates with the outside world.

Knowing these interfaces clarifies deployment and how Django handles requests under the hood.

Under the Hood

When you start a Django project, the framework creates a folder structure that separates concerns: configuration, apps, templates, and static files. manage.py acts as a command-line utility that sets environment variables and calls Django's internal commands. The project folder contains settings.py which loads configurations into memory. Apps are Python packages with models, views, and migrations that Django loads dynamically. URL routing uses urls.py to map web requests to view functions. The WSGI or ASGI files expose the app to web servers, which forward HTTP requests to Django. Migrations are Python files that describe database schema changes and are applied in order to keep the database consistent with models.

Why designed this way?

Django was designed to follow the principle of 'Don't Repeat Yourself' and to promote clean, maintainable code. The project structure enforces separation of concerns, making it easier to work on different parts independently. The use of apps allows modular development and reuse. The command-line tool manage.py simplifies common tasks. WSGI/ASGI interfaces follow Python web standards to ensure compatibility with many servers. This structure evolved from early web frameworks that mixed code and configuration, which became hard to maintain.

┌───────────────┐
│  manage.py    │
└──────┬────────┘
       │ runs commands
┌──────▼────────┐
│ Project Folder│
│ ┌───────────┐ │
│ │settings.py│ │
│ │urls.py    │ │
│ │wsgi.py    │ │
│ └───────────┘ │
│               │
│ ┌───────────┐ │
│ │ app1/     │ │
│ │ ┌───────┐ │ │
│ │ │models │ │ │
│ │ │views  │ │ │
│ │ │migrations││ │
│ │ └───────┘ │ │
│ └───────────┘ │
└───────────────┘

Myth Busters - 4 Common Misconceptions

Quick: Do you think manage.py runs your app by itself without any other files? Commit to yes or no.

Common Belief: manage.py is the main program that runs the Django app entirely on its own.

Reality: manage.py is a helper script that sets up the environment and calls Django commands; the actual app runs through WSGI/ASGI interfaces and the Django framework.

Why it matters: Thinking manage.py runs the app alone can confuse deployment and debugging, leading to errors when trying to run the app in production.

Quick: Do you think all your app code must be inside the main project folder? Commit to yes or no.

Common Belief: All code must live inside the main project folder created by Django.

Reality: Apps are separate Python packages and can live outside the main project folder or be reused across projects.

Why it matters: Believing this limits modularity and reuse, making projects harder to scale and maintain.

Quick: Do you think templates are Python files? Commit to yes or no.

Common Belief: Templates are Python code files that generate HTML.

Reality: Templates are HTML files with special syntax for dynamic content, separate from Python code.

Why it matters: Confusing templates with Python code can cause mixing logic and presentation, making the app harder to maintain.

Quick: Do you think migrations automatically update your database without running commands? Commit to yes or no.

Common Belief: Once you change models.py, the database updates automatically without extra steps.

Reality: You must create and apply migrations manually using manage.py commands to update the database.

Why it matters: Assuming automatic updates can cause data loss or mismatches between code and database.

Expert Zone

1

Django's project structure supports multiple settings files for different environments, but beginners often overlook this and keep all settings in one file, risking security and deployment issues.

2

The apps folder can be placed anywhere in your Python path, allowing for reusable apps across projects, which is a powerful but underused feature.

3

WSGI and ASGI serve different purposes: WSGI is synchronous and widely supported, while ASGI supports async and websockets, enabling modern real-time features.

When NOT to use

Django's default project structure is not ideal for very small scripts or microservices where a full framework is overkill. In such cases, lightweight frameworks like Flask or FastAPI may be better. Also, for highly customized architectures, you might reorganize the structure, but this requires deep Django knowledge.

Production Patterns

In production, projects often split settings into base, development, and production files. Apps are organized by domain or feature. Static files are collected into a single folder for efficient serving. WSGI or ASGI servers like Gunicorn or Daphne run the app behind a reverse proxy. Continuous integration pipelines run tests and migrations automatically. This structure supports scaling and team collaboration.

Connections

Modular Programming

Django apps embody modular programming by separating features into independent units.

Understanding modular programming helps grasp why Django encourages apps as reusable, self-contained components.

MVC Architecture

Django's project structure follows the Model-View-Controller pattern, organizing code into models, views, and templates (views).

Knowing MVC clarifies why Django separates data, logic, and presentation into different files and folders.

Urban Planning

Like city zoning divides areas for homes, shops, and parks, Django's structure divides code into apps, templates, and static files.

Seeing project structure as urban planning highlights the importance of clear organization for growth and maintenance.

Common Pitfalls

#1 Trying to put all code in settings.py for convenience.

Wrong approach:

def my_view(request):
return HttpResponse('Hello')

# inside settings.py

Correct approach:

Create a separate views.py file inside an app folder and define my_view there.

Root cause:

Misunderstanding the purpose of settings.py as configuration only, not code logic.

#2 Not creating migrations after changing models.

Wrong approach:

Changing models.py but never running 'python manage.py makemigrations' or 'migrate'.

Correct approach:

Run 'python manage.py makemigrations' and then 'python manage.py migrate' after model changes.

Root cause:

Assuming Django updates the database automatically without explicit migration commands.

#3 Placing templates inside app folders without configuring TEMPLATE_DIRS.

Wrong approach:

templates/ folder inside app but not added to settings.py, so templates not found.

Correct approach:

Add app templates path to settings.py or use app directories template loader.

Root cause:

Not understanding how Django finds templates and the need to configure template directories.

Key Takeaways

Django project structure organizes your code into clear parts: project settings, apps, templates, and static files.

manage.py is your command tool to run and manage the project but does not run the app alone.

Apps are modular units inside a project that help keep features separate and reusable.

Migrations track database changes and must be created and applied explicitly to keep data safe.

WSGI and ASGI files connect your Django app to web servers, enabling it to handle web requests.