Project Structure & Apps

django-admin startproject config .

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

mkdir apps && touch apps/__init__.py
for app in core accounts catalog reviews api; do
  django-admin startapp "$app" "apps/$app"
done

from django.apps import AppConfig


class CatalogConfig(AppConfig):
    name = "apps.catalog"   # full dotted path: apps/ is a package
    label = "catalog"       # short name used in tables, migrations and "app_label.Model"

from django.apps import apps

for config in apps.get_app_configs():
    print(config.label, config.name, len(list(config.get_models())))

apps.get_app_config("reviews")        # AppConfig; LookupError if unknown
apps.is_installed("apps.reviews")     # takes the full name, returns a bool
apps.get_model("reviews.Review")      # or get_model("reviews", "Review")

import logging

from django.apps import AppConfig

logger = logging.getLogger(__name__)


class ReviewsConfig(AppConfig):
    name = "apps.reviews"
    label = "reviews"

    def ready(self):
        # Importing the module is what connects its @receiver functions.
        # Models may be imported here; database queries may not.
        from . import signals  # noqa: F401

        logger.debug("reviews app ready")

import logging

from django.db.models.signals import post_save
from django.dispatch import receiver

logger = logging.getLogger(__name__)


# A string sender ("app_label.ModelName") avoids importing the model class.
@receiver(post_save, sender="reviews.Review", dispatch_uid="reviews.log_new_review")
def log_new_review(sender, instance, created, **kwargs):
    if created:
        logger.info("new review %s for book %s", instance.pk, instance.book_id)

def test_signal_is_connected_by_ready(self):
    with self.assertLogs("apps.reviews.signals", level="INFO") as logs:
        Review.objects.create(book=self.book, author=self.user, rating=5)
    self.assertIn("new review", logs.output[0])

config/
  __init__.py
  asgi.py             # DJANGO_SETTINGS_MODULE default: config.settings.production
  wsgi.py             # DJANGO_SETTINGS_MODULE default: config.settings.production
  urls.py
  settings/
    __init__.py       # empty
    base.py           # everything shared
    local.py          # developer machine
    test.py           # test runs
    production.py     # deployment, everything sensitive from the environment
manage.py             # DJANGO_SETTINGS_MODULE default: config.settings.local

os.environ.setdefault("DJANGO_SETTINGS_MODULE", "config.settings.local")        # manage.py
os.environ.setdefault("DJANGO_SETTINGS_MODULE", "config.settings.production")   # asgi.py, wsgi.py

"""Settings shared by every environment."""

from pathlib import Path

# config/settings/base.py -> project root is three levels up
BASE_DIR = Path(__file__).resolve().parent.parent.parent

INSTALLED_APPS = [
    "django.contrib.admin",
    "django.contrib.auth",
    "django.contrib.contenttypes",
    "django.contrib.sessions",
    "django.contrib.messages",
    "django.contrib.staticfiles",
    # Bookshelf apps, ordered from the most basic to the most dependent
    "apps.core",
    "apps.accounts",
    "apps.catalog",
    "apps.reviews",
    "apps.api",
]

AUTH_USER_MODEL = "accounts.User"

ROOT_URLCONF = "config.urls"
WSGI_APPLICATION = "config.wsgi.application"
ASGI_APPLICATION = "config.asgi.application"

TEMPLATES = [
    {
        "BACKEND": "django.template.backends.django.DjangoTemplates",
        "DIRS": [BASE_DIR / "templates"],  # project-level templates
        "APP_DIRS": True,                  # plus templates/ folders inside each app
        "OPTIONS": {
            "context_processors": [
                "django.template.context_processors.request",
                "django.contrib.auth.context_processors.auth",
                "django.contrib.messages.context_processors.messages",
            ],
        },
    },
]

STATICFILES_DIRS = [BASE_DIR / "static"]
LOCALE_PATHS = [BASE_DIR / "locale"]
# No DEFAULT_AUTO_FIELD line: BigAutoField is the default since Django 6.0.

"""Developer machine: readable errors, throw-away secret key."""

import os

from django.core.management.utils import get_random_secret_key

from .base import *  # noqa: F403

DEBUG = True
ALLOWED_HOSTS = ["localhost", "127.0.0.1", "[::1]"]
# A fresh key per process is fine for development (sessions reset on restart).
SECRET_KEY = os.environ.get("DJANGO_SECRET_KEY", get_random_secret_key())

"""Test runs: fast hashers, no real services."""

from .local import *  # noqa: F403

PASSWORD_HASHERS = ["django.contrib.auth.hashers.MD5PasswordHasher"]

"""Production: everything sensitive comes from the environment."""

import os

from .base import *  # noqa: F403

DEBUG = False
SECRET_KEY = os.environ["DJANGO_SECRET_KEY"]  # KeyError at start-up if missing
ALLOWED_HOSTS = os.environ["DJANGO_ALLOWED_HOSTS"].split(",")

SECURE_SSL_REDIRECT = True
SESSION_COOKIE_SECURE = True
CSRF_COOKIE_SECURE = True
SECURE_HSTS_SECONDS = 31536000
SECURE_HSTS_INCLUDE_SUBDOMAINS = True
SECURE_HSTS_PRELOAD = True

python manage.py check
# System check identified no issues (0 silenced).

DJANGO_SETTINGS_MODULE=config.settings.test python manage.py test
# Ran 4 tests in 0.014s ... OK

DJANGO_SECRET_KEY="$(python -c 'from django.core.management.utils import get_random_secret_key as g; print(g())')" \
DJANGO_ALLOWED_HOSTS=bookshelf.example.com \
DJANGO_SETTINGS_MODULE=config.settings.production python manage.py check --deploy
# System check identified no issues (0 silenced).

DJANGO_SETTINGS_MODULE=config.settings.production python manage.py check
# KeyError: 'DJANGO_SECRET_KEY'

from django.db import models


class TimeStampedModel(models.Model):
    """Abstract base: created/modified timestamps for every model that wants them."""

    created_at = models.DateTimeField(auto_now_add=True)
    updated_at = models.DateTimeField(auto_now=True)

    class Meta:
        abstract = True

from django.db import models
from django.urls import reverse

from apps.core.models import TimeStampedModel


class Author(TimeStampedModel):
    name = models.CharField(max_length=200)

    def __str__(self):
        return self.name


class Book(TimeStampedModel):
    title = models.CharField(max_length=200)
    author = models.ForeignKey(Author, on_delete=models.PROTECT, related_name="books")

    def __str__(self):
        return self.title

    def get_absolute_url(self):
        return reverse("catalog:book-detail", args=[self.pk])

pip install cookiecutter
cookiecutter https://github.com/cookiecutter/cookiecutter-django

bookshelf/
  manage.py
  pyproject.toml            # dependencies and tooling; uv.lock is generated
  .python-version           # 3.14
  config/
    settings/{base,local,production,test}.py
    urls.py  wsgi.py
  bookshelf/                # the "project slug" package holds the apps
    users/                  # apps.py, models.py, views.py, admin.py, forms.py, tests/
    contrib/sites/          # migrations override for django.contrib.sites
    templates/  static/
    conftest.py
  tests/  locale/  docs/  utility/  .envs/  .pre-commit-config.yaml  README.md  LICENSE

from django.conf import settings
from django.db import models

from apps.catalog.models import Book
from apps.core.models import TimeStampedModel


class Review(TimeStampedModel):
    book = models.ForeignKey(Book, on_delete=models.CASCADE, related_name="reviews")
    author = models.ForeignKey(settings.AUTH_USER_MODEL, on_delete=models.CASCADE)
    rating = models.PositiveSmallIntegerField()
    body = models.TextField(blank=True)

    class Meta:
        constraints = [
            models.UniqueConstraint(fields=["book", "author"], name="one_review_per_user_and_book"),
            models.CheckConstraint(condition=models.Q(rating__gte=1, rating__lte=5), name="rating_between_1_and_5"),
        ]

from django.db import IntegrityError, transaction

from .models import Review


class ReviewError(Exception):
    """Raised when a review cannot be added; views translate it to HTTP."""


def add_review(*, book, user, rating, body=""):
    """Business rule: one review per user and book, rating from 1 to 5."""
    if not 1 <= rating <= 5:
        raise ReviewError("rating must be between 1 and 5")
    try:
        with transaction.atomic():
            return Review.objects.create(book=book, author=user, rating=rating, body=body)
    except IntegrityError as exc:
        raise ReviewError("you already reviewed this book") from exc

from django.contrib.auth.decorators import login_required
from django.http import HttpResponseBadRequest
from django.shortcuts import get_object_or_404, redirect
from django.views.decorators.http import require_POST

from apps.catalog.models import Book

from .services import ReviewError, add_review


@login_required
@require_POST
def create_review(request, book_id):
    book = get_object_or_404(Book, pk=book_id)
    try:
        add_review(
            book=book,
            user=request.user,
            rating=int(request.POST.get("rating", 0)),
            body=request.POST.get("body", ""),
        )
    except ReviewError as exc:
        return HttpResponseBadRequest(str(exc))
    return redirect(book)

{% extends "base.html" %}
{% block content %}
<h1>{{ book.title }}</h1>
<form method="post" action="{% url 'reviews:create' book.pk %}">
  {% csrf_token %}
  <input type="number" name="rating" min="1" max="5" required>
  <textarea name="body"></textarea>
  <button type="submit">Add review</button>
</form>
{% endblock %}

def test_post_creates_review_then_rejects_duplicate(self):
    self.client.force_login(self.user)
    url = reverse("reviews:create", args=[self.book.pk])
    first = self.client.post(url, {"rating": 4, "body": "Great"})
    self.assertRedirects(first, self.book.get_absolute_url(), fetch_redirect_response=False)
    self.assertEqual(Review.objects.count(), 1)
    self.assertEqual(self.client.post(url, {"rating": 3}).status_code, 400)
    self.assertEqual(Review.objects.count(), 1)

def test_get_is_not_allowed_and_anonymous_is_redirected(self):
    url = reverse("reviews:create", args=[self.book.pk])
    self.assertEqual(self.client.post(url, {"rating": 4}).status_code, 302)  # to login
    self.client.force_login(self.user)
    self.assertEqual(self.client.get(url).status_code, 405)

bookshelf/
  manage.py
  pyproject.toml
  config/
    settings/{base,local,test,production}.py
    urls.py  asgi.py  wsgi.py
  apps/
    core/        # abstract models, shared helpers (imports nothing from the other apps)
    accounts/    # custom User (email login), sign-up, password reset
    catalog/     # Author, Book: public pages, search, pagination
    reviews/     # Review: services.py, signals.py, moderation tasks and emails
    api/         # versioned REST API (DRF, with a Django Ninja variant)
  templates/     # project-level: base.html, registration/
  static/        # project-level assets
  locale/        # translations (English, Spanish)
  tests/         # cross-app and end-to-end tests

[project]
name = "bookshelf"
version = "0.1.0"
requires-python = ">=3.12"
dependencies = [
    "django>=6.1,<6.2",
    "psycopg[binary]>=3.3",
    "django-environ>=0.14",
]

[dependency-groups]
dev = [
    "pytest-django>=4.14",
    "factory-boy>=3.3",
]

[tool.pytest.ini_options]
DJANGO_SETTINGS_MODULE = "config.settings.test"
python_files = ["tests.py", "test_*.py"]