Project Structure

Key features

• Generated once by `django-admin startproject`, at the project root
• Automatically sets DJANGO_SETTINGS_MODULE — no --settings flag needed
• Runs the exact same commands as django-admin (runserver, migrate, ...)
• `python manage.py test` and `python manage.py shell` are the other two used daily
• Also usable as `python -m django`, with the same settings-detection behavior

Command

python manage.py runserver
python manage.py migrate
python manage.py shell
python manage.py test

Key features

• Generated empty by startapp — `from django.db import models` is the only starting line
• One models.py per app; large apps sometimes split into a models/ package instead
• makemigrations scans this file (per app) to detect schema changes
• views.py, admin.py, and serializers all import model classes FROM here
• See `django.fundamentals.models` for how a model class itself works

Command

# <app>/models.py
from django.db import models

class MyModel(models.Model):
    name = models.CharField(max_length=100)

Key features

• Generated empty by startapp — no starting boilerplate beyond the file existing
• Holds every function-based or class-based view the app defines
• Imports models from `.models`, referenced by name from that app's urls.py
• A large app can split views.py into a views/ package, mirroring models/
• See `django.fundamentals.views` for the HttpRequest/HttpResponse contract itself

Command

# <app>/views.py
from django.shortcuts import render
from .models import MyModel

def my_view(request):
    return render(request, "app/template.html", {})

Key features

• Generated by startapp, one migrations/ directory per app, with an __init__.py
• Files are numbered sequentially: 0001_initial.py, 0002_add_field.py, ...
• makemigrations generates a new file by diffing models.py against the last one
• migrate applies pending migrations, tracked in Django's own migration history table
• Meant to be committed to version control — the schema history is part of the codebase

Command

python manage.py makemigrations
python manage.py migrate

Key features

• Lives at mysite/mysite/settings.py — inside the inner package, not the project root
• Generated once by startproject, then hand-edited as the project grows
• INSTALLED_APPS, MIDDLEWARE, DATABASES, and ROOT_URLCONF all live here
• A large project often splits this into a settings/ package (base/dev/prod) — see below
• See `django.fundamentals.settings` for how DJANGO_SETTINGS_MODULE picks this file

Command

mysite/
    manage.py
    mysite/
        __init__.py
        settings.py   # <- here
        urls.py
        asgi.py
        wsgi.py

Key features

• Lives at mysite/mysite/urls.py, alongside settings.py
• ROOT_URLCONF (a setting) points at this module by dotted path
• Best practice: mostly include() calls, one per app, not inline app routes
• admin.site.urls is almost always included here directly, unlike app routes
• See `django.fundamentals.url-configuration` for path()/include() mechanics

Command

# mysite/urls.py
from django.contrib import admin
from django.urls import include, path

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

Key features

• Generated by `python manage.py startapp <name>`, one AppConfig subclass per app
• name is required — the full Python path to the app (e.g. "billing")
• verbose_name gives a human-readable label, shown in the admin site
• ready() is the hook for signal registration — see `django.fundamentals.app-registry`
• INSTALLED_APPS usually just lists the app name; Django finds this config automatically

Command

# <app>/apps.py
from django.apps import AppConfig

class MyAppConfig(AppConfig):
    name = "myapp"

Key features

• Generated by startapp with `from django.contrib import admin` and nothing else
• admin.site.register(Model) is the minimum needed to manage a model there
• A model NOT registered here simply does not appear in /admin/ — no error
• ModelAdmin subclasses (list_display, etc.) also live in this file
• See `django.fundamentals.admin` for what a ModelAdmin can customize

Command

# <app>/admin.py
from django.contrib import admin
from .models import MyModel

admin.site.register(MyModel)

Key features

• Generated by startapp with `from django.test import TestCase` and nothing else
• django.test.TestCase wraps each test in a transaction, rolled back after
• Always subclass TestCase, not plain unittest.TestCase, for database-touching tests
• `python manage.py test` discovers every test*.py file and TestCase subclass automatically
• A large app can split tests.py into a tests/ package (test_models.py, test_views.py, ...)

Command

# <app>/tests.py
from django.test import TestCase

class MyTestCase(TestCase):
    def test_something(self):
        self.assertTrue(True)

Key features

• Not generated by startapp — added by convention, unlike models.py/views.py/admin.py
• app_name sets a namespace, so {% url 'billing:list' %} is unambiguous
• Included from the project's root urls.py via include("app.urls")
• Its own urlpatterns only need patterns relative to whatever prefix include() gave it
• See `django.project-structure.urls-py` for the root file that includes this one

Command

# <app>/urls.py
from django.urls import path
from . import views

app_name = "myapp"
urlpatterns = [
    path("", views.index, name="index"),
]

Key features

• APP_DIRS = True (the default) makes Django look in each app's own templates/
• TEMPLATES[0]["DIRS"] lists extra, project-wide template directories
• Convention: templates/<app_name>/file.html, not templates/file.html directly
• {% extends %} and {% include %} both resolve against this same combined search path
• render(request, "billing/detail.html", ...) — the app-name prefix is part of the path

Command

billing/
    templates/
        billing/
            list.html
            detail.html

Key features

• Each app's own static/ is discovered automatically via django.contrib.staticfiles
• STATICFILES_DIRS lists extra, project-wide static directories
• Convention: static/<app_name>/file.css, mirroring templates/<app_name>/
• collectstatic merges every source into one STATIC_ROOT for production
• See `django.fundamentals.static-files` for STATIC_URL and the {% static %} tag itself

Command

billing/
    static/
        billing/
            invoice.css
            invoice.js