Следим за тем чтобы были разделены следующие слои приложения:

• конфиги приложения (работаем с env)
• зависимости
• миграции
• модели
• слой работы с данными (запросы в апи, с3, бд, кафку и т д)
• бизнес логика
• web интерфейс
• единая точка входа где описаны все команды для приложения

Для соблюдения такого подхода в сервисах организована структура вида:

Директория с логикой приложения. Описанием всех usecase-ов, моделей, и тд. Содержит следующие директории:

• models - модели сущностей с которыми работает приложение (alembic, marshmallow, etc)
• repositories - уровень данных. отвечает за логику создания, доступа, редактирования. Не содержит бизнес логики.
• services - уровень бизнес логики. Этот уровень не знает про web и не знает про низкоуровневые детали хранения сущностей (БД, s3, файловая система, другие сервисы и пр.)

Директория с логикой работы web приложения. Описание endpoint'ов, построение apispec, и пр.

• routes.py - определяет перечень всех endpoint'ов
• api - директория, содержит описание endpoint'ов: схемы входных/выходных параметров, apispec, код вызова определенного сервиса из app/services.

• settings - Настройки приложения, константы и переменные окружения.
• helpers / utils - Общие инструменты не содержащие бизнес-логики
• requirements - Директория с описанием зависимостей приложения
• docker-compose.yml - поднимает все зависимости приложения (БД, s3, очереди), для локальной разработки
• manage.py - единая точка входа где описаны все консольные команды для приложения

Проект конфигурируется с помощью pyproject.toml файла (вместо setup.cfg и requirements.txt), который содержит dev и prod зависимости, конфиги линтеров и pytest'а.

В качестве пакетного менеджера используем uv (ссылка на документацию в confluence). Версии всех зависимостей фиксируем в uv.lock файле в корне проекта. uv.lock генерируется uv автоматически.

Пример типового Dockerfile (python3.10):

FROM python:3.10-slim

WORKDIR /app

COPY pyproject.toml uv.lock ./

RUN pip install uv && \
    uv sync --frozen

COPY . .

CMD ["python", "manage.py", "runserver"]

Чтобы тесты не оказывались в билде, добавляем .dockerignore файл, который возволяет исключить файлы из контекста билда. В .dockerignore файле должна быть директория tests/

Шаблонный вариант Makefile'а с часто используемыми командами