Project structure · Backend
Django project structure
Opens with creditsFor students building their first serious Python web app or API with Django, and for the team that keeps it running years later. The project is a thin "config" package plus one Django app per business area (accounts, catalog, orders, core), each owning its models, services, views, API, migrations and tests. Settings come from validated environment variables, and the tree grows from the tutorial layout to CI, containers, observability and enforced module boundaries.
Curated by Tauseef FayyazBeginner193 files and foldersDjango 6.1 (same layout on 5.2 LTS), Python 3.14 (3.12+ supported), Django REST framework 3.18Checked October 2026How it grows
Each stage opens the explorer there
- 1Day 1What the scaffold and your first hour give you37 files and folders
- 2GrowingWhat a real app with features and tests adds+81 files and folders
- ProductionWhat running it for real users adds+42 files and foldersOpens with credits
- ExpertWhat a team needs to keep it healthy for years+33 files and foldersOpens with credits
How it is organised
- One Django app per business area (accounts, catalog, orders), not per file type: an app owns its models, services, views, API, migrations and tests, so you can read or move a feature in one place.
- Keep the project package (config) thin: settings, root URLs, the API router, logging and the ASGI and WSGI entry points only. No models or views live there.
- Settings come from environment variables, read and type-checked in one place (django-environ), with small per-environment modules (dev, test, prod) for the differences. A missing secret in production should crash at startup, not at the first request.
- Start with a custom user model on day 1. Django recommends it, and switching after the first migration is painful.
- Thin views, services for writes, selectors for reads: business rules live in plain functions so HTML views, API views, admin actions, management commands and tasks all share them.
- Django REST framework is optional. Add serializers and API views when something other than your own templates (a React app, a mobile app) needs JSON, and publish an OpenAPI schema from day one of the API.
- Tests grow in layers: fast unit and request tests per app, integration tests against a real PostgreSQL in a container, then contract, load and mutation tests once a team depends on the API.
- Boundaries are written down and checked: core imports nothing from feature apps, and feature apps talk through services, enforced by import-linter in CI once the codebase is big enough to drift.
At the top of the project
Open one in the explorer for the full story
- shop/
- .venv/The virtual environment uv creates, holding Django and every other installed package.
- .git/Git history for the project. `uv init` runs `git init` for you.
- .gitignoreTells Git what never to commit: .venv, .env, db.sqlite3, staticfiles, media, caches, coverage output.
- .python-versionThe Python version uv uses for this project, written by `uv init`.
- .editorconfigIndentation, line endings and final newline rules every editor understands.
- pyproject.tomlProject metadata, dependencies and tool settings (pytest, coverage, ruff, mypy, mutmut) in one file.
- uv.lockThe exact version of every package, direct and indirect, that uv resolved.
- README.mdHow to install, run, test and deploy the project.
- manage.pyThe command line entry point: runserver, makemigrations, migrate, createsuperuser, shell, your own commands.
- db.sqlite3The local SQLite database the default settings create on your first migrate.
- .vscode/Shared VS Code settings: interpreter, formatter, test discovery and a debug config for runserver.3 inside
- .devcontainer/A container definition so the project opens ready to run in VS Code or GitHub Codespaces.1 inside
- config/The project package startproject generates: settings, root URLs, ASGI and WSGI entry points.7 inside
- accounts/The app that holds your custom User model, login pages and the "who am I" API, created before the first migrate.8 inside
- catalog/The second feature app: products customers can order, with a read-only public API.9 inside
- orders/The example feature app: everything about orders, from model to service to API to tests.19 inside
- core/A small app for project-wide pieces: base models, middleware, API error handling, pagination, health checks.6 inside
- templates/Project-wide templates: base.html layout, login pages and error pages shared by every app.2 inside
- static/Your own CSS, JavaScript and images, listed in STATICFILES_DIRS.1 inside
- media/User uploads (MEDIA_ROOT) during local development.
- htmlcov/The HTML coverage report from `pytest --cov --cov-report=html`.
- conftest.pyProject-wide pytest fixtures: a customer, a logged-in client, an API client.
- .envYour local secrets and database URL. Never committed.
- .env.exampleEvery environment variable the app needs, with safe placeholder values. Committed.
- compose.yamlDocker Compose for local services: PostgreSQL, Redis for cache and throttles, Mailpit for emails.
- justfileShort names for the commands everyone runs: just dev, just test, just lint, just migrate.
- .pre-commit-config.yamlRuns ruff lint and format, keeps uv.lock in sync and blocks committed secrets, on every commit.
- AGENTS.mdInstructions for AI coding agents: how to run, test and structure code in this repo.
- CLAUDE.mdClaude Code's project instructions: one line, `@AGENTS.md`, pointing at the shared file.
Learn more on Sefism
Roadmaps, cheat sheets and projects that go with Django.
- Roadmap· PythonBackend development roadmapAPIs, databases, auth, deploys
- Roadmap· Django and ReactFull stack development roadmapBuild and ship whole web apps
- RoadmapSQL and databases roadmapQueries, design, indexes, transactions
- RoadmapChoosing the right database roadmapSQL, document, cache, search, vector and more
- Cheat sheetBackend development cheat sheetAPIs, databases, auth, deploys.
- Cheat sheetSQL and databases cheat sheetQueries, design, indexes, transactions.
- FYP idea· BeginnerTuition Centre Fee and Attendance Manager with Parent RemindersA web app for small tuition centres and academies to manage batches, take attendance from a phone, generate monthly fee vouchers and send parents reminders. A beginner-friendly final year project with a real paying customer in almost every neighbourhood.
- FYP idea· BeginnerRent Ledger and Tenant Portal for Small LandlordsA web app for small landlords and property caretakers with a few houses, flats or shops to track agreements, monthly rent with yearly increments, utility bills, security deposits and repair requests, with a simple tenant portal. A beginner-friendly final year project in real estate and property management.
- FYP idea· IntermediateJob Shop Work Order Tracker for Small ManufacturersA web app for small manufacturers and job shops (fabrication, furniture, printing, garments) to turn customer orders into work orders, track each operation on the shop floor from a shared tablet, and compare quoted versus actual time and cost. An intermediate final year project in manufacturing software.
See 9 moreShow fewer
- QuestionI understand tutorials but cannot build anything myself. Why does coding feel so different when I am alone?Tutorials train recognition, not production. When you follow along, someone else makes every decision. Building alone requires you to break a problem down and make choices, which is a separate skill. Build it with small projects, planning on paper first, and a rule to struggle before you look anything up.
- QuestionI am graduating soon and feel like I learned four years of theory but cannot actually build software. What now?The gap between theory and building is common and closable. Building is a separate skill: breaking a vague idea into small steps, using real tools and finishing. Close it with one guided build, then one project you design yourself, shipped in small working slices. Your theory will start to make sense along the way.
- QuestionShould I learn Python or JavaScript first?Choose based on what you want to build. JavaScript if you want web development, since it runs in every browser. Python if you are drawn to data, AI, automation or backend scripting. Both are excellent first languages, and the second one is far easier once you know the first well.
- QuestionHow do I learn Git and GitHub properly instead of just copying commands?Learn the model first: commits are snapshots, branches are pointers, and remotes are copies. Then use Git daily on your own projects, practise a team workflow with branches and pull requests, and break things on purpose, such as merge conflicts, so you learn to recover calmly.
- Resource· GuideDjango Tutorial (official)Django's official eight part tutorial, which builds a small polls app while covering projects and apps, models and the ORM, the admin, views and templates, forms and generic views, automated testing, static files and admin customisation. It is accurate, updated with each Django release (the stable docs were for Django 6.1 in September 2026) and teaches the conventions the rest of the docs assume.
- Resource· GuideDjango REST FrameworkThe official documentation for Django REST framework (DRF), the standard toolkit for building web APIs with Django. A quickstart and a multi part tutorial cover serializers, requests and responses, class based views, authentication and permissions, relationships and hyperlinked APIs, viewsets and routers, and the API guide documents pagination, filtering, throttling, versioning and schemas. For Django developers building JSON APIs.
- Resource· Guidepytest DocumentationThe official documentation for pytest, the most widely used Python testing framework. It shows how to write tests as plain functions with ordinary assert statements, share setup through fixtures, run one test against many inputs, and extend the tool with plugins. The twenty-minute getting started guide is enough to put tests around a small project, and the rest works as a reference as your suite grows.
- Resource· Tooluv DocumentationThe official docs for uv, the fast Python package and project manager from Astral. It replaces pip, virtualenv, pip-tools and pyenv for most projects, and its lockfile is what makes an ML project install the same way on your laptop, in CI and in a Docker image. Free, open source and quick to learn.
- Resource· GuideOWASP API Security Top 10The OWASP API Security Top 10 (2023 edition) lists the most critical security risks in APIs, led by broken object level authorisation, broken authentication and broken object property level authorisation. Each risk comes with attack scenarios and prevention advice. It suits anyone building or reviewing backends, because these flaws are common, easy to miss in code review and often invisible in normal testing.
Checked against 21 official sources, October 2026. If something has changed, the docs win.Show sourcesHide sources
- Django tutorial part 1: what startproject and startapp generate
- Django settings and DJANGO_SETTINGS_MODULE
- Django deployment checklist
- Django custom user model
- Django Content Security Policy (new in 6.0)
- Django security overview
- Django background Tasks framework
- Django data migrations
- django-tasks-db: database backend and db_worker
- django-environ
- Django REST framework: permissions and throttling
- drf-spectacular
- pytest-django: database setup hooks
- factory_boy with Django
- Testcontainers for Python: PostgreSQL
- import-linter contracts
- Schemathesis
- OpenTelemetry Python: Django instrumentation
- Sentry for Django
- uv: using uv in Docker
- GitHub Dependabot: supported ecosystems (uv)
Best practices and checklists for this stack
Picked from the other libraries by shared topics.
Best practices
See all- REST API Design Best PracticesDesign HTTP APIs clients enjoy using: resources and URLs, methods, status codes, problem details errors, pagination, idempotency keys, ETags, versioning and OpenAPI.
- TypeScript Best PracticesModern TypeScript best practices for 2026: strict settings, TypeScript 7, modeling data with unions, safe narrowing, runtime validation, generics and typed linting.
- Authentication Best PracticesBuild sign-in that holds up: password rules from NIST, Argon2id hashing, login throttling, MFA and passkeys, secure sessions and safe account recovery.
Checklists
See all- Database Migration ChecklistCheck a schema or data migration before it ships: expand and contract, lock behaviour, online indexes, batched backfills, rehearsal on real data, backups, rollback, deploy order and monitoring.
- Production Readiness ChecklistCheck a service before it takes real traffic: ownership, SLOs, capacity, timeouts and retries, alerts, rollout and rollback, backups, security and on-call.
- API Security ChecklistCheck your REST or GraphQL API against the OWASP API Security Top 10: authentication, object authorization, rate limits, input validation, SSRF, CORS and logging.
Work with me
Stuck on something specific?
Writing only gets you so far. If you want an answer to your situation rather than the general case, book a session and we will work through it together. Sessions are free for approved Sefism members, and a few slots open each week.
- 1:1 Mentorship
- Fresh Graduate Mentorship
- Career Guidance
Brand deals, promos and partnerships: tauseeffayyaz@gmail.com