dj-scaffold

Scaffold an op-django Project

You are preparing a Django project to use the op-django patterns. After this skill runs, the dj-architecture and dj-signals skills can add features on top without any further setup.

BEFORE WRITING CODE

Figure out which situation you're in:

• Greenfield — no Django project exists yet. You will run uv init and django-admin startproject, then transform the result.
• Existing Django project — a manage.py, settings.py, and at least one app already exist. You will add the src/project/ shell alongside what's there and relocate files only if asked.

Read pyproject.toml (if present) and locate manage.py and settings.py so you know the project's current layout. Confirm with the user before moving any existing files.

Target Layout

src/
  manage.py
  project/
    __init__.py
    settings.py
    urls.py
    wsgi.py
    asgi.py
    api/
      __init__.py   # NinjaAPI() instance, exception handlers, mounts all resource routers
      <resource>/
        __init__.py  # re-exports router
        routes.py    # handler functions
        schemas.py   # ninja.Schema input types
    types.py        # AuthedRequest and other shared typing aliases
    ids.py          # prefixed ULID generators
    services.py    # svcs registry + get() helper
    signals.py     # ReliableSignal base + send_reliable machinery
  <app>/
    __init__.py
    apps.py
    admin.py
    models/
      __init__.py
      <entity>.py
    dtos/
      __init__.py
      <entity>.py
    repositories/
      __init__.py
      <entity>.py
    services/
      __init__.py
      <entity>.py
    signals.py      # optional, defines ReliableSignal instances
    receivers.py    # optional, @receiver handlers — must be idempotent
tests/
  <app>/
    test_repo.py
    test_service.py
    test_api.py
pyproject.toml

Per-app models/, dtos/, repositories/, services/ are packages, not single files — one module per entity.

Step 1: Dependencies

Use uv for everything. Never pip or poetry.