CLAUDE.md Template: Django Ninja + CockroachDB + Custom Token Session Auth + Django ORM Configuration

Overview

The CLAUDE.md template is a copyable Claude Code blueprint for building a Django Ninja API backed by CockroachDB with a custom token-session authentication flow using Django ORM configuration. This page targets developers who want a ready-to-paste CLAUDE.md block and stack-specific guidance for Django Ninja + CockroachDB.

Direct answer: This CLAUDE.md Template provides a stack-specific, production-ready Claude Code block plus architectural and operational rules you can apply to a Django Ninja project using CockroachDB and a custom token-session auth workflow.

When to Use This CLAUDE.md Template

• You are building a Django Ninja API that must scale with CockroachDB.
• You need a standard CLAUDE.md block to document architecture, security, tests, and deployment for this stack.
• You want a copy-paste-ready Claude Code block to seed documentation and onboarding.

Copyable CLAUDE.md Template

# CLAUDE.md

Project role:
- You are a senior backend engineer. You orchestrate a Django Ninja API backed by CockroachDB and implement a robust custom token-session authentication flow using Django ORM configuration.

Architecture rules:
- Use Django as the runtime and Django Ninja for API definitions.
- CockroachDB is the primary database; use PostgreSQL-compatible settings and the psycopg2/psycopg3 driver.
- All API endpoints must be defined via Django Ninja routers with explicit type hints and validators.
- Secrets must be sourced from environment variables; never commit credentials.

File structure rules:
- Maintain a Django project layout with a single source of truth in config/ and apps/api/
- Use a dedicated app for API endpoints (apps/api/)
- Include a separate tests/ directory under the API app
- Requirements.txt should pin Django, django-ninja, psycopg2-binary, and any auth libs

Authentication rules:
- Implement a Custom Token Session Auth endpoint:
  - POST /auth/token/ to issue a token for valid credentials
  - Use HttpOnly secure cookies or token headers depending on client
  - Tokens are hashed and stored with expiry; cannot be easily forged
- Override default Django authentication to use the custom token flow for API requests
- Tokens must be invalidated on logout and after expiry

Database rules:
- Configure CockroachDB as the default DATABASES backend using a PostgreSQL-compatible engine
- Use a dedicated User model with UUID primary keys where applicable
- Enforce migrations for schema changes; never run without migrations in production

Validation rules:
- Use Django model validators and Django Ninja pydantic-like schemas for request validation
- Validate all inputs server-side; return explicit field-level errors

Security rules:
- Do not store secret keys in code; use environment-based secret management
- Enable CSRF protection for non-API endpoints; disable only for sanctioned API calls with token auth
- Use HttpOnly, Secure cookies for tokens when possible
- Hash tokens in the database and rotate them regularly

Testing rules:
- Use pytest-django for unit and integration tests
- Include tests for authentication, API endpoints, and database interactions
- Run migrations during test setup and mock external services where applicable

Deployment rules:
- Use Gunicorn with Django WSGI server or an ASGI adapter if you upgrade to Django channels
- Use a robust reverse proxy and proper TLS termination
- Pin dependencies and lock file in production builds

Things Claude must not do:
- Do not fabricate database schemas or endpoints that do not exist
- Do not bypass migrations or security checks
- Do not hard-code secrets or sample tokens in the CLAUDE.md template
- Do not assume SQLite; CockroachDB must be used in production

Recommended Project Structure

Stack-specific directory layout for Django Ninja + CockroachDB with a custom token session authentication:

django_ninja_cockroachdb/
├── manage.py
├── config/
│   ├── __init__.py
│   ├── asgi.py
│   ├── settings.py
│   └── urls.py
├── apps/
│   └── api/
│       ├── __init__.py
│       ├── models.py
│       ├── api.py
│       ├── schemas.py
│       ├── router.py
│       └── tests/
├── requirements.txt
└── .env

Core Engineering Principles

• Security by default: treat token data and credentials as highly sensitive and encrypted at rest and in transit.
• Declarative configuration: centralize settings in Django settings and environment variables; Claude Code should not obscure them.
• Idempotent deploys: migrations must be safe to re-run; avoid destructive schema changes without a plan.
• Strict separation: API layer (Django Ninja) is clearly separated from ORM models and database concerns.
• PostgreSQL compatibility: CockroachDB is used with PostgreSQL-compatible settings; avoid vendor-specific shortcuts.

Code Construction Rules

• Prefer explicit types in Django Ninja schemas; always validate inputs.
• Keep authentication logic in a dedicated module; avoid scattering token logic across views.
• Define a clear model for tokens with expiry and rotation semantics.
• Use Django ORM and querysets for all data access; minimize raw SQL usage.
• Document all API endpoints with precise request/response schemas in the CLAUDE.md block.

Security and Production Rules

• Store secrets in environment variables; never commit to VCS.
• Use HttpOnly cookies for tokens or secure headers; enable TLS in all environments.
• Rotate tokens regularly and invalidate on logout; audit token usage patterns.
• Enable database access controls and least-privilege users for CockroachDB.

Testing Checklist

• Unit tests for models and utilities; ensure validators catch invalid data.
• Integration tests for authentication flow and API endpoints using Django test client or pytest-django.
• Migration tests to verify schema changes do not break existing data.
• End-to-end tests simulating token issuance, refresh, and invalidation.

Common Mistakes to Avoid

• Assuming SQLite or other DBs in production; CockroachDB is required here.
• Storing tokens in plaintext or not hashing them.
• Skipping migrations during deployment; keep schema in sync with models.
• Hard-coding secrets or credentials in code or CLAUDE.md blocks.

FAQ

What is this CLAUDE.md Template for Django Ninja + CockroachDB?

A copyable Claude Code CLAUDE.md instruction block for a Django Ninja API backed by CockroachDB with a custom token-session authentication flow, plus ORM configuration.

Does this template assume CockroachDB is PostgreSQL-compatible?

Yes. The template configures Django DATABASES to use a PostgreSQL-compatible CockroachDB driver and settings.

How do I apply the provided CLAUDE.md block?

Copy the block into CLAUDE.md in your repository and follow the instructions to implement roles, architecture, and rules for this stack.

What testing framework is recommended?

pytest-django for unit and integration tests; ensure migrations run during test setup.

Can I adapt this template to other stacks?

The template is stack-specific but can be adapted with caution to similar Django-based stacks; replace stack-specific rules accordingly.