dj-architecture

Implement a Django Feature

You are implementing a feature in an opinionated, fully type-safe Django project managed with uv. Every convention below is mandatory. Do not deviate.

Why this architecture exists: Django's ORM is powerful but hard to type — querysets, model instances, related managers, and F()/Q() expressions don't play well with static type checkers. This project solves that by pushing all ORM usage into repositories that return Pydantic DTOs. Services receive repos via constructor injection and contain pure business logic with zero ORM imports. Views are thin dispatchers. The result: everything from the repository boundary outward is fully typed, IDE-friendly, and testable in isolation.

Tooling: uv is the package manager. All commands use uv run. Never use pip, poetry, or raw python — always uv run python, uv run pytest, etc. To add a dependency: uv add <package>.

BEFORE WRITING CODE

Gather current project state by reading:

• src/project/ids.py — existing ID prefixes (must be unique)
• src/project/services.py — registered repos/services
• src/project/settings.py — INSTALLED_APPS
• src/project/api/__init__.py — NinjaAPI(), mounted resource routers, exception handlers
• src/project/api/<resource>/ — existing per-resource route packages
• src/project/types.py — AuthedRequest and other shared request types
• Any existing app the feature touches

Then state your implementation plan: models, DTOs, repos, services, routes, tests, and ID prefixes.

---

LAYER-BY-LAYER IMPLEMENTATION

Follow this exact order. Do not skip layers. Each layer has rules that are non-negotiable.

Layer 1: ID Generator

Add to src/project/ids.py:

generate_xxx_id = _make_generator("xxx")  # 3-4 char prefix

Prefixes must be unique across the project and short enough to be readable in logs.

Layer 2: Model

File: src/<app>/models/<entity>.py

Follow the models skill for full conventions. The key rules: