dj-architecture

Enforce a strict layered Django architecture with ULID keys and Pydantic DTOs.

109|6|Updated Apr 4, 2026
One-click install
npx skills add https://github.com/dvf/opinionated-django --skill dj-architecture
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: dj-architecture
Source: https://github.com/dvf/opinionated-django/tree/main/skills/dj-architecture
Command: npx skills add https://github.com/dvf/opinionated-django --skill dj-architecture

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

Django projects often suffer from inconsistent architecture, ORM leakage across layers, and untestable business logic, leading to codebases that are hard to maintain and scale as the project grows.

Core Features & Use Cases

  • Enforces a strict 5-layer architecture (API, Service, DTO, Repository, Model) with clear separation of concerns
  • Uses prefixed ULID primary keys, Pydantic DTOs for typed layer boundaries, and svcs for dependency injection
  • Includes conventions for django-ninja APIs, Celery reliable signals, and comprehensive layered testing
  • Ideal for adding new entities, endpoints, or business logic to Django projects that prioritize testability and maintainability

Quick Start

Use the dj-architecture skill to implement a new order management feature with API endpoints, repository layer, and unit tests in your existing opinionated Django project.

Frequently Asked Questions about dj-architecture

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I prevent Django ORM leakage across architectural layers?

To prevent Django ORM leakage, you can enforce a strict 5-layer architecture separating API, Service, DTO, Repository, and Model components. Using Pydantic DTOs at layer boundaries ensures type safety and stops ORM queries from leaking into business logic.

How do I structure a new Django entity with django-ninja and Celery?

Structuring a new Django entity involves defining django-ninja API routes, repository layers, and Celery reliable signals for async side-effects. This strict separation ensures business logic remains decoupled from API routing and background task execution.

Does this layered Django architecture pattern support dependency injection?

Yes, this layered Django architecture pattern supports dependency injection using the svcs library. Injecting dependencies through defined boundaries improves code testability and maintainability across your service and repository layers.

What is the best way to add type-safe DTOs to a Django project?

The best way to add type-safe DTOs to a Django project is using Pydantic models at layer boundaries. Defining Pydantic DTOs separates internal ORM models from external API contracts, eliminating data leakage and improving validation.

Why should I use prefixed ULID primary keys in Django models?

Prefixed ULID primary keys should be used in Django models to provide globally unique, time-sortable identifiers without exposing sequential database row counts. This opinionated convention enhances scalability and data integrity across distributed systems.

How do I write comprehensive tests for layered Django business logic?

Comprehensive tests for layered Django business logic are written by targeting the Service and Repository layers independently using injected dependencies. Isolating layers through svcs dependency injection allows precise unit testing without hitting the database.