# System Architecture & Invariants: Django 6 & Ninja / DRF Architecture Specialist

## 1. System Overview
Production guidelines for Django 6. Enforces async ORM methods, Django Ninja Pydantic schemas, strict migrations, N+1 query elimination, and the built-in tasks and CSP support.
All AI agents operating within this repository must adhere strictly to these architectural boundaries.

### Technology Stack
- **Framework**: Django 6 / Django Ninja / DRF
- **Language Standard**: Python 3.12+
- **UI & Styling**: None / API Service
- **Data Persistence**: PostgreSQL / Django ORM
- **Engineering Philosophy**: strict

## 2. Core Architectural Invariants
- **Clean Layered Architecture**: Decouple presentation, business logic, and data access layers via interfaces.
- **Guard Clauses & Early Returns**: Exit early from functions to eliminate deeply nested if-else pyramids.
- **Schema-Driven Boundaries**: Validate all external data (API, forms, env) with Zod or Pydantic schemas; on failure, reject with a typed error and never pass unvalidated data onward.

## 3. Data Flow & State Management Principles
1. **Unidirectional Data Flow**: State flows top-down; mutations flow through explicit, typed handlers.
2. **Boundary Validation**: External inputs (API payloads, query parameters, environment variables) must be parsed with strict schemas before reaching domain logic.
3. **Surgical Precision**: Diffs must remain minimal and scoped exclusively to the objective. Do not reformat unrelated code.

## 4. Forbidden Anti-Patterns & Operational Guardrails
- **Inspect Before Acting**: Always read and understand existing code and imports before suggesting changes.
- **Minimal Surgical Diffs**: Touch only lines relevant to prompt. Preserve existing comments and formatting.
- **Propose Verification Steps**: With every modification, specify concrete commands or tests to verify correctness.
- **Concise & Direct Tone**: Skip conversational pleasantries. Deliver focused diffs and a short rationale.

## 5. Domain-Specific Invariants
- Never execute raw SQL without query parameterization.
- Ensure all model fields declare explicit verbose_name and db_index where filtered.

## 6. Implementation Reference Patterns

### Preferred Pattern
```python
from ninja import Router, Schema
from django.shortcuts import aget_object_or_404
from .models import Article

router = Router()

class ArticleOut(Schema):
    id: int
    title: str
    author_name: str

@router.get("/articles/{article_id}", response=ArticleOut)
async def get_article(request, article_id: int):
    article = await Article.objects.select_related("author").aget(id=article_id)
    return {"id": article.id, "title": article.title, "author_name": article.author.username}
```

### Forbidden Anti-Pattern
```python
@router.get("/articles/{article_id}")
async def get_article(request, article_id: int):
    article = Article.objects.get(id=article_id) # Blocking sync query inside async handler!
    return {"id": article.id, "title": article.title, "author": article.author.username}
```

## 7. Verification Protocol
Before finalizing any implementation:
1. Use asynchronous ORM methods (aget, acreate, afirst) inside async view handlers.
2. Prevent N+1 queries: always apply select_related for foreign keys and prefetch_related for M2M relations.
3. Validate API payloads with Django Ninja Schema or DRF Serializers before domain logic execution.
4. Never modify existing committed migration files; create new sequential migrations via makemigrations.
5. Use GeneratedField for database-computed columns rather than overriding model save().
6. Run background work with django.tasks (@task, .enqueue()) and a real worker backend; the built-in backends are for development and tests.
7. Set the Content Security Policy with SECURE_CSP and ContentSecurityPolicyMiddleware instead of a third-party package.