Django Ninja + MySQL + JWT Simple-JWT Auth + Django ORM Scaled Blueprint – CLAUDE.md Template | CLAUDE.md template

Overview

The CLAUDE.md template explains how to implement a scalable Django Ninja API backed by MySQL with JWT-based authentication using SimpleJWT, all wired through the Django ORM. This is a copyable CLAUDE.md template page focused on the Django Ninja + MySQL + JWT Simple-JWT Auth stack, designed to be pasted into Claude Code for rapid scaffolding. Direct answer: use this template to bootstrap a secure, scalable API with Django Ninja, MySQL, and JWT authentication.

When to Use This CLAUDE.md Template

• You need a clean, repeatable blueprint for a Django Ninja API backed by MySQL.
• You want token-based authentication using JWT (SimpleJWT) with secure cookie storage.
• You require strict model validation, serialization, and API endpoint organization via Django ORM.
• You plan to deploy in a containerized or cloud environment with production-grade settings.

Copyable CLAUDE.md Template

# CLAUDE.md

Project role: Lead Django Ninja API Engineer focused on scalable MySQL-backed auth with JWT.

Architecture rules:
- Use a Django project with apps, Django Ninja for API routes, and Django ORM for data models.
- Use MySQL as the primary database with proper settings for charset utf8mb4 and connection pooling.
- Use djangorestframework-simplejwt for JWT authentication with access/refresh tokens and HttpOnly cookies.
- Structure APIs by feature modules; keep business logic in services where possible.
- Ensure idempotent write paths and durable migrations.

File structure rules:
- manage.py at repo root
- config/ for settings
- apps/ to house feature apps (models, serializers, endpoints)
- requirements.txt or poetry.lock for dependencies
- tests/ with pytest-django setup

Authentication rules:
- Use SimpleJWT with access token expiry (short) and refresh token expiry (long).
- Store tokens in HttpOnly cookies; avoid localStorage.
- Enforce token rotation on refresh and blacklist revoked tokens.
- Protect API views with JWTAuth and appropriate permissions.

Database rules:
- MySQL database with proper user privileges.
- Use Django migrations for schema changes.
- Index foreign keys and frequently queried fields.

Validation rules:
- Rely on Django Ninja request schemas (pydantic models) with strict type checks.
- Validate all inputs server-side; return 400 with detailed errors.

Security rules:
- Set CSRF exemption only for token-authenticated API endpoints.
- Enable CORS with safe origins only; use allowed origins list.
- Use environment-based secrets; do not commit SECRET_KEY.

Testing rules:
- Use pytest-django; cover model validations, API endpoints, and auth flows.
- Mock external calls; verify token generation/refresh flows.

Deployment rules:
- Dockerized deployment with Gunicorn and Nginx; use multi-stage builds.
- Use environment variables for DB credentials, JWT signing key, and allowed origins.
- Collect static files and run migrations on startup.

Things Claude must not do:
- Do not bypass Django ORM migrations for schema changes.
- Do not embed raw SQL strings in business logic.
- Do not hardcode secrets in source code.
- Do not bypass authentication checks on protected endpoints.

Recommended Project Structure

.
├── manage.py
├── config/
│   ├── __init__.py
│   ├── settings.py
│   ├── urls.py
│   └── wsgi.py
├── apps/
│   └── api/            # feature app for API endpoints
│       ├── __init__.py
│       ├── models.py
│       ├── serializers.py
│       ├── endpoints.py
│       ├── urls.py
│       └── tests/
├── requirements.txt
<= Note: Docker-related files can live here for production deployments

Core Engineering Principles

• Explicit data modeling with Django ORM and clear boundaries between apps.
• Declarative validation using Django Ninja and pydantic models.
• API-first design with stable, versioned endpoints.
• Security-by-default: tokens, cookies, CORS, and proper secret handling.
• Observability: structured logging and metrics from production-grade deployments.

Code Construction Rules

• Define API schemas with Django Ninja; use typed pydantic models for request/response payloads.
• Keep database access through Django ORM; avoid raw SQL in handlers.
• Use SimpleJWT for authentication; configure access and refresh lifetimes in settings.
• Environment-driven configuration: DB, secrets, allowed origins via env vars.
• Write tests that exercise token flows and protected endpoints.
• Document API contracts alongside code; keep CLAUDE.md blocks up-to-date.

Security and Production Rules

• Use HTTPS in all environments; configure Nginx as a reverse proxy.
• HttpOnly, Secure cookies for JWT tokens; enable SameSite.Strict where appropriate.
• Rotate refresh tokens on use; blacklist revoked tokens.
• Set ALLOWED_HOSTS and proper CSRF handling; restrict origins via CORS.
• Secure secret management; do not commit SECRET_KEY or DB credentials.

Testing Checklist

• Unit tests for models and serializers; test validation errors.
• Integration tests for login, token rotation, and protected endpoints.
• End-to-end tests for critical API flows using test client with JWTs.
• CI checks for migrations and lints on push/PRs.

Common Mistakes to Avoid

• Hardcoding credentials or secrets in source code.
• Skipping migrations or making in-memory schema changes.
• Not validating inputs properly or exposing overly permissive endpoints.
• Using non-httpOnly storage for JWTs or insecure cookie flags.

FAQ

What stack does this CLAUDE.md template cover?

It covers Django Ninja, MySQL, JWT Simple-JWT authentication, and Django ORM for a scalable API blueprint.

Can this template be adapted to PostgreSQL?

Yes, but adjust DB settings and migrations for PostgreSQL-specific behavior.

How should tokens be stored?

Store access and refresh tokens in HttpOnly cookies with Secure and SameSite attributes.

What are recommended deployment steps?

Containerize with Docker, use Gunicorn + Nginx, and ensure environment variables are supplied in production.

What should I avoid?

Avoid hardcoding secrets, avoid bypassing migrations, and avoid raw SQL in application logic.