Skip to content
Kuza Ndoto Academy

Project Structure

IntermediateChapter 1 · Page 4 of 234 min readUpdated 15 Nov 2026

startproject and startapp generate several files for you. Knowing what each one does helps you find your way around any Django codebase, including ones written by other people.

The complete layout

After creating the campus project and the events app, and running migrate, your folder looks like this:

campus-events/
├── .venv/              virtual environment (never edit by hand)
├── db.sqlite3          the database, created by migrate
├── manage.py           command-line helper for this project
├── requirements.txt    list of installed packages
├── campus/             project configuration package
│   ├── __init__.py
│   ├── asgi.py
│   ├── settings.py
│   ├── urls.py
│   └── wsgi.py
└── events/             an app
    ├── __init__.py
    ├── admin.py
    ├── apps.py
    ├── migrations/
    │   └── __init__.py
    ├── models.py
    ├── tests.py
    └── views.py

Project-level files

manage.py

A small script that runs Django commands for this specific project. It sets the DJANGO_SETTINGS_MODULE environment variable to campus.settings and then hands over to Django. You use it constantly:

python manage.py runserver        # start the development server
python manage.py startapp events  # create an app
python manage.py makemigrations   # prepare database changes
python manage.py migrate          # apply database changes
python manage.py createsuperuser  # create an admin user
python manage.py shell            # Python shell with Django loaded

You almost never need to edit manage.py itself.

campus/settings.py

The control panel for the whole project. Some of the settings you'll touch most:

SettingWhat it controls
SECRET_KEYA secret value used to sign cookies and tokens. Must be kept private in production.
DEBUGShows detailed error pages when True. Must be False on a live site.
ALLOWED_HOSTSDomain names the site may be served from.
INSTALLED_APPSThe apps that are switched on.
MIDDLEWARECode that runs on every request and response (security, sessions, CSRF).
TEMPLATESWhere Django looks for template files.
DATABASESWhich database to use. The default is a SQLite file, db.sqlite3.
TIME_ZONE, LANGUAGE_CODELocal time zone and default language.
STATIC_URLThe URL prefix for CSS, JavaScript and images.

For a site in Kenya, Uganda or Tanzania, set the time zone to East Africa Time. Keep USE_TZ = True so Django stores times safely in UTC and converts them for display.

campus/settings.py

LANGUAGE_CODE = "en-us"

TIME_ZONE = "Africa/Nairobi"

USE_I18N = True

USE_TZ = True

campus/urls.py

The project's main URL list, sometimes called the root URLconf. Every request starts here. The generated file contains a single route for the admin site:

from django.contrib import admin
from django.urls import path

urlpatterns = [
    path("admin/", admin.site.urls),
]

You'll extend it on the URL Routing page.

campus/wsgi.py and campus/asgi.py

Entry points for production web servers. WSGI is the traditional standard used by servers such as Gunicorn; ASGI is the newer standard that also supports asynchronous features like WebSockets. Each file creates an object called application that the server calls. You'll point Gunicorn at campus.wsgi when you deploy.

__init__.py

An empty file that tells Python "this folder is a package", so you can write imports like from campus import settings.

App-level files

FilePurposeCovered in
models.pyClasses that describe your database tablesModels
views.pyFunctions or classes that handle requestsWriting Views
admin.pyRegisters models with the admin dashboardThe Admin Site
apps.pyConfiguration class for the app (name, default ID field type)This page
migrations/Generated files that record database changesMigrations
tests.pyAutomated tests for the app-

Files you add yourself

Django doesn't generate everything. As the app grows you'll add these by hand:

events/
├── urls.py                  the app's own URL patterns
├── forms.py                 form classes
├── templates/
│   └── events/              templates, namespaced by app name
│       ├── event_list.html
│       └── event_detail.html
└── static/
    └── events/              CSS, JavaScript and images
        └── style.css

Notice the repeated events folder inside templates/ and static/. This is called namespacing. Django searches the template folders of every installed app, so if two apps both had a file called templates/index.html, one would hide the other. Putting files in templates/events/ and referring to them as "events/event_list.html" avoids the clash.

Common mistake

Committing db.sqlite3, .venv/ or a real SECRET_KEY to a public GitHub repository. Add the first two to .gitignore, and read Settings & Security to learn how to keep secrets out of your code.

Key points

  • manage.py runs commands; settings.py configures the project; urls.py is where every request starts.
  • wsgi.py and asgi.py connect your project to production servers.
  • Each app has its own models.py, views.py, admin.py and migrations/.
  • Add urls.py, forms.py, templates/app_name/ and static/app_name/ yourself.
Up next · New chapter: URLs & ViewsThe MVT PatternModels, views and templates explained.
→

Tip: use the ← and → keys to move between pages.