django project structure

structure.md

Django Project Structure

Доменно-орієнтована архітектура з Clean Architecture / DDD підходом.

project-root/
│
├── apps/                          # доменно-орієнтовані застосунки
│   ├── users/                     # домен: користувачі
│   │   ├── api/                   # http/graphql контролери, роутери
│   │   ├── models/                # сутності / ORM-моделі
│   │   ├── services/              # бізнес-логіка (application layer)
│   │   ├── repositories/          # доступ до даних
│   │   ├── use_cases/             # юзкейси (CQRS / actions)
│   │   ├── dto/                   # data transfer objects
│   │   ├── schemas/               # валідація вхідних даних (Pydantic / DRF)
│   │   ├── permissions/           # авторизаційна логіка
│   │   ├── admin/                 # Django admin для домену
│   │   └── tests/                 # юніт-тести домену
│   │
│   ├── billing/                   # домен: білінг
│   │   ├── api/
│   │   ├── models/
│   │   ├── services/
│   │   ├── repositories/
│   │   ├── use_cases/
│   │   ├── dto/
│   │   ├── schemas/
│   │   ├── tasks/
│   │   ├── permissions/
│   │   ├── admin/
│   │   └── tests/
│   │
│   ├── notifications/             # домен: сповіщення
│   │   └── ...                    # та сама структура
│   │
│   └── core/                      # спільні доменні речі (base models)
│       ├── models/
│       ├── services/
│       └── utils/
│
├── config/                        # конфігурація застосунку
│   ├── settings/
│   │   ├── base.py
│   │   ├── dev.py
│   │   ├── prod.py
│   │   ├── test.py
│   │   ├── database.py
│   │   ├── cache.py
│   │   ├── logging.py
│   │   ├── email.py
│   │   └── security.py
│   └── urls.py
│
├── infrastructure/                # технічна інфраструктура
│   ├── db/                        # міграції, db utils
│   ├── cache/                     # redis, cache backends
│   ├── external_api/              # клієнти до зовнішніх API
│   ├── storage/                   # local storage abstractions
│   ├── healthcheck/               # health endpoints
│   └── base_repo/                 # базові абстракції репозиторіїв
│       ├── base.py
│       └── mixins.py
│
├── services/                      # загальні інфраструктурні сервіси
│   ├── email_service/
│   ├── payment_gateway/
│   ├── messaging/
│   ├── sms_service/
│   └── storage/
│
├── shared/                        # спільні компоненти між доменами
│   ├── exceptions/
│   ├── utils/
│   ├── constants/
│   ├── types/
│   ├── enums/
│   ├── middleware/
│   └── mixins/
│
├── tests/                         # глобальні інтеграційні / e2e тести
│   ├── integration/
│   ├── e2e/
│   └── factories/
│
├── docker/
│   ├── Dockerfile
│   ├── docker-compose.yml
│   └── docker-compose.dev.yml
│
├── scripts/
│   ├── entrypoint.sh
│   ├── seed_db.py
│   └── generate_schema.py
│
├── docs/
│   ├── architecture.md
│   ├── api_reference.md
│   └── adr/                       # Architecture Decision Records
│
├── .github/                       # CI/CD workflows
│   └── workflows/
│
├── main.py                        # точка входу (ASGI/WSGI)
├── manage.py
├── wsgi.py
├── asgi.py
├── pyproject.toml                 # залежності + linting конфіг
├── Makefile                       # команди: run, test, lint, migrate...
├── .env.example
├── .pre-commit-config.yaml
├── README.md
└── CHANGELOG.md

---

Ключові принципи

Кожен домен (apps/*/) містить

Папка	Призначення
api/	HTTP/GraphQL контролери, router, views
models/	ORM-моделі, сутності
services/	Бізнес-логіка, application layer
repositories/	Доступ до даних, query logic
use_cases/	CQRS-юзкейси, actions
dto/	Data Transfer Objects (output)
schemas/	Валідація вхідних даних (Pydantic / DRF Serializers)
events/	Доменні події, Django signals
tasks/	Celery-таски, прив'язані до домену
permissions/	Авторизаційна логіка (DRF permissions)
admin/	Django admin реєстрація
tests/	Юніт-тести домену

Важливі рішення

• repositories/ тільки на рівні домену — глобальний repositories/ відсутній. Абстракції живуть в infrastructure/base_repo/, конкретні реалізації — в apps/*/repositories/.
• schemas/ ≠ dto/ — schemas/ для валідації вхідних даних, dto/ для вихідних (response objects).
• events/ ізолюють сигнали — Django signals і доменні події не розповзаються по моделях.
• docs/adr/ — Architecture Decision Records для ключових рішень команди.