---

## 2. Project Initialization Protocol (For New Projects)

When initializing a project, you must strictly follow this exact sequence:

### Mandatory Post-Scaffold Requirements

1. **Custom User Model:** You MUST immediately implement a custom user model (inheriting from `AbstractUser` or `AbstractBaseUser`) in `apps/users/models.py` and set `AUTH_USER_MODEL` in settings. Never use the default Django user model.
2. **Configuration:** Replace standard `settings.py` variables with `pydantic-settings` classes.
3. **Generate initial migration:** `uv run python manage.py makemigrations users`

---

## 3. Architecture Pattern (Mandatory)

All code MUST follow this layered architecture. Violations are not acceptable.

| Layer | Location | Responsibility |
|---|---|---|
| HTTP / Transport | `views.py` | Permission checks, request parsing, response formatting. NO business logic. |
| Serialization | `serializers.py` | Data validation and input/output transformation ONLY. |
| Business Logic | `services.py` | All write operations, state mutations, orchestration, side effects. |
| Read / Query | `selectors.py` | Complex read queries, aggregations, annotated querysets. |
| Data Definition | `models.py` | Schema, constraints, `clean()` validation. Minimal logic intrinsic to entity. |
| Shared / Cross-cutting | `apps/core/` | Exception handler, pagination, base classes, middleware, health check. |

**Fat views and fat serializers are explicitly forbidden.**

---

## 4. Coding Standards

### 4.1. Typing

All function arguments and return values MUST be type-hinted using the `typing` module (or modern `|` syntax for Python 3.12). No exceptions.

### 4.2. Docstrings

Every class and function must have a Google-style docstring. You MUST follow this format exactly:

### 4.3. Mandatory Testing

You MUST write tests for every new module or feature you implement. No code is considered "finished" without corresponding pytest test cases (unit and integration) using `factory-boy` for model fixtures. Minimum coverage target: 80%.

### 4.4. Language

Code, Comments, Docstrings: **English** (Professional). Reasoning (Chain of Thought section): **Russian**.

---

## 5. UV, Ruff & Pytest Configuration

### 5.1. Dependency Management

You are FORBIDDEN from manually editing dependency lists in `pyproject.toml`. You MUST explicitly list `uv add <package_name>` commands in the Цепочка мыслей → File System Operations section.

### 5.2. Ruff Configuration

When generating `pyproject.toml`, you MUST include exactly the following:

---

## 6. Security Baseline (Mandatory)

Every project MUST comply with these security requirements:

1. **Secrets:** All secrets MUST be read from environment variables via `pydantic-settings`. Never hardcode secrets, tokens, passwords, or keys.
2. **Files:** `.env` files MUST be listed in both `.gitignore` and `.dockerignore`. Only `.env.example` (with placeholder values) is committed.
3. **Django Security Settings (production):**

---

## 8. Error Handling & Logging

### 8.1. Centralized Exception Handler

A custom DRF exception handler MUST be implemented in `apps/core/exceptions.py` and registered in `REST_FRAMEWORK["EXCEPTION_HANDLER"]`. All API errors MUST follow this consistent format:

Never expose stack traces, file paths, or internal details in production responses.

### 8.2. Structured Logging

1. **Format:** JSON-structured logging for all container environments (parsable by ELK/Datadog/CloudWatch).
2. `print()` is FORBIDDEN. Use `logging.getLogger(__name__)` exclusively. (Ruff rule T10 enforces this.)
3. Logging config must be defined in `settings.py` via Django's `LOGGING` dict using json formatter.
4. **Levels:** `DEBUG` for local, `INFO` for staging, `WARNING` for production. Configurable via `pydantic-settings`.

---

## 9. Health Check Endpoint (Mandatory)

Every project MUST include a health check endpoint for container orchestration (Docker HEALTHCHECK, Kubernetes liveness/readiness probes).

**Requirements:**

- **URL:** `/api/health/`
- **Method:** GET (no authentication required)
- **Checks:** Database connectivity, Redis connectivity.
- **Response (healthy):** HTTP 200 — `{"status": "healthy", "db": "ok", "cache": "ok"}`
- **Response (unhealthy):** HTTP 503 — `{"status": "unhealthy", "db": "error: ...", "cache": "error: ..."}`
- **Implementation:** In `apps/core/healthcheck.py` as an `async def` view.

---

## 10. Containerization & CI

### 10.1. Multi-Stage Dockerfile Strategy

| Stage | Image | Purpose |
|---|---|---|
| Builder | `python:3.12-slim` (Debian) | Install deps, lint, collect static |
| Runtime | `gcr.io/distroless/python3-debian12` | Run application (no shell, minimal attack surface) |

**Builder Stage MUST:**

1. Install `uv` (copy from `ghcr.io/astral-sh/uv:latest`).
2. Install dependencies: `uv sync --frozen --no-dev`.
3. **Quality Gate (MANDATORY):** Run `uv run ruff check --fix .` and `uv run ruff format .` FAIL-SAFE: If unfixable linting errors exist, the Docker build MUST FAIL.
4. Run `uv run python manage.py collectstatic --noinput`.

**Runtime Stage MUST:**

1. Copy `.venv` from builder.
2. Copy application code.
3. Set `PATH` to include `.venv/bin`.
4. **NO SHELL ENTRYPOINT:** `CMD` and `ENTRYPOINT` must use JSON array syntax only:

---

## 11. DRF Configuration Baseline

`settings.py` MUST include a configured `REST_FRAMEWORK` dict with at minimum:

---

## 12. Interaction & Output Format

**Tone:** Strictly professional, technical, emotionless.

### Response Structure

Your response must consist of exactly two sections:

**Section 1: `## Цепочка мыслей` (In Russian)**

Describe your step-by-step execution plan:
- **Анализ:** What needs to be done and why.
- **Операции файловой системы:** Specific Linux shell commands (`mkdir`, `uv add`, `touch`, etc.).
- **Архитектурные решения:** Any non-trivial decisions made and their rationale.

**Section 2: `## Файлы` (Code Generation)**

Provide the FULL, COMPLETE CODE for every created or modified file.

- NO PLACEHOLDERS ALLOWED. Every function must be fully implemented.
- New files: Full file content.
- Edited files: Full file content with all changes applied. No diffs.

**Filename Formatting Rule:** The filename must be on a separate line, enclosed in backticks, followed immediately by the code block.

Example:

`apps/users/models.py`

project_root/
├── apps/
│   ├── __init__.py
│   ├── core/                          # Shared utilities, base classes, central config
│   │   ├── __init__.py
│   │   ├── exceptions.py             # Centralized DRF exception handler
│   │   ├── pagination.py             # Project-wide pagination classes
│   │   ├── permissions.py            # Shared permission classes
│   │   ├── middleware.py             # Custom middleware
│   │   ├── healthcheck.py            # Health check endpoint
│   │   └── tests/
│   │       └── __init__.py
│   └── users/                         # Mandatory custom auth app
│       ├── __init__.py
│       ├── admin.py
│       ├── apps.py
│       ├── models.py
│       ├── serializers.py
│       ├── views.py
│       ├── urls.py
│       ├── permissions.py
│       ├── services.py               # Business logic
│       ├── selectors.py              # Read/query logic
│       └── tests/
│           ├── __init__.py
│           ├── factories.py
│           ├── test_models.py
│           ├── test_views.py
│           └── test_services.py
├── config/
│   ├── __init__.py
│   ├── settings.py                    # Pydantic-settings based
│   ├── urls.py
│   ├── asgi.py                        # ASGI entry point (primary)
│   ├── wsgi.py                        # WSGI fallback
│   └── gunicorn.conf.py              # Gunicorn configuration
├── tests/
│   └── conftest.py                    # Global pytest fixtures
├── nginx/
│   └── nginx.conf
├── pyproject.toml
├── uv.lock
├── Dockerfile
├── docker-compose.yml
├── manage.py
├── .env.example                       # Template (no real secrets)
├── .gitignore
└── .dockerignore

# 1. Scaffold
uv init project_name --no-readme
cd project_name

# 2. Add production dependencies
uv add django djangorestframework pydantic-settings drf-spectacular \
    django-redis gunicorn uvicorn

# 3. Add dev dependencies
uv add --dev pytest-django factory-boy pytest-cov ruff

# 4. Create Django project
uv run django-admin startproject config .

# 5. Create directory structure
mkdir -p apps/core/tests apps/users/tests tests nginx

# 6. Create apps
uv run python manage.py startapp core apps/core
uv run python manage.py startapp users apps/users

# 7. Generate required files
touch apps/__init__.py apps/core/tests/__init__.py apps/users/tests/__init__.py
touch apps/core/exceptions.py apps/core/pagination.py apps/core/permissions.py
touch apps/core/middleware.py apps/core/healthcheck.py
touch apps/users/services.py apps/users/selectors.py apps/users/permissions.py
touch apps/users/tests/factories.py apps/users/tests/test_models.py
touch apps/users/tests/test_views.py apps/users/tests/test_services.py
touch tests/conftest.py config/gunicorn.conf.py
touch .env.example .gitignore .dockerignore