CLAUDE.md Template: FastAPI + MySQL + Tortoise ORM + Auth0 Token Verification Microservice CLAUDE.md template

Overview

The CLAUDE.md template demonstrates how to scaffold a FastAPI microservice that authenticates requests with Auth0 tokens, stores data in MySQL via Tortoise ORM, and exposes a token-verified API surface. This page is a copyable CLAUDE.md template page that developers can paste into Claude Code to bootstrap a production-ready stack for this exact set of technologies.

When to Use This CLAUDE.md Template

• You are building a FastAPI-based microservice protected by Auth0 tokens.
• You need a MySQL datastore accessed through Tortoise ORM's async API.
• You want a clear, copyable CLAUDE.md template that enforces token verification on endpoints by default.
• You require a clean project structure with explicit authentication, DB models, and test coverage.

Copyable CLAUDE.md Template

# CLAUDE.md
- Project role: You are an expert backend engineer designing a FastAPI + MySQL + Tortoise ORM + Auth0 token verification microservice. Your output must be a complete, drop-in CLAUDE.md template that guides developers through implementation and testing for this stack.
- Architecture rules:
  - Build a single-responsibility FastAPI service that handles authentication, data access, and business logic via dependency injection.
  - Use Auth0 for authentication with RS256, validate issuer, audience, and token expiry, and cache JWKS for performance.
  - Persist data in MySQL using Tortoise ORM. Use async calls everywhere; avoid blocking IO.
  - Separate concerns via modules: api (endpoints), models (Tortoise ORM), schemas (Pydantic models), core/config, and auth utilities.
- File structure rules:
  - app/
    - main.py
    - config.py
    - api/
      - v1/
        - endpoints/
          - auth.py
          - users.py
    - models/
      - __init__.py
      - user.py
    - schemas/
      - __init__.py
      - user.py
    - auth/
      - auth_utils.py
      - jwt.py
    - db/
      - tortoise_config.py
      - init_db.py
    - tests/
  - migrations/
  - docker/
  - docker-compose.yml
  - requirements.txt
- Authentication rules:
  - Validate JWTs issued by Auth0 using the JWKS endpoint. Check 'aud' and 'iss' claims. Reject tokens with expired 'exp'.
  - Attach user identity to FastAPI request state and expose through dependencies.
  - Do not bypass token validation on protected endpoints.
- Database rules:
  - Use MySQL with Tortoise ORM; configure TORTOISE_ORM with MySQL dialect.
  - Define at least a User model with id, email, and roles. Enforce unique email. Use migrations for schema changes.
  - Use async migrations when updating schemas.
- Validation rules:
  - Use Pydantic models for request validation and response schemas.
  - Enforce strict types where possible (e.g., emails, IDs as UUIDs).
- Security rules:
  - Do not log raw tokens or JWT details in production logs.
  - Enforce HTTPS, rotate secrets, and use environment-based configuration.
  - Never bypass authentication or authorization checks.
- Testing rules:
  - Unit tests for validators and auth utilities.
  - Integration tests for endpoints using httpx.AsyncClient with a test Auth0-simulated token.
  - Include a basic end-to-end test scaffold that can run in CI.
- Deployment rules:
  - Provide a Dockerfile and docker-compose.yml for local development and production-like environments.
  - Use env vars for sensitive config; mount secrets securely in production.
  - Health checks and proper container startup order.
- Things Claude must not do:
  - Do not generate blocking I/O in async paths.
  - Do not bypass token verification or hard-code credentials.
  - Do not assume an in-memory database for production-like scenarios.
# END CLAUDE.md

Recommended Project Structure

app/
  main.py
  config.py
  api/
    v1/
      endpoints/
        auth.py
        users.py
  models/
    __init__.py
    user.py
  schemas/
    __init__.py
    user.py
  auth/
    auth_utils.py
    jwt.py
  db/
    tortoise_config.py
    init_db.py
 tests/
 migrations/
 docker/
  Dockerfile
  docker-compose.yml
 requirements.txt

Core Engineering Principles

• Async-first by default: use async FastAPI routes and async ORM operations.
• Clear separation of concerns: API, auth, data access, and config live in isolated modules.
• Strong typing: use Pydantic for validation and Tortoise ORM models for data integrity.
• Security-by-default: enforce Auth0 validation on protected endpoints and avoid token exposure.
• Observability: include structured logging, metrics, and tracing hooks for auth flows.

Code Construction Rules

• Use FastAPI with APIRouter for versioned endpoints.
• Configure Tortoise ORM with a MySQL database using an async config (TORTOISE_ORM).
• Implement a reusable dependency to verify Auth0 JWTs on protected endpoints.
• Validate all inputs with Pydantic models and return consistent response envelopes.
• Dependency-inject core services to ease testing and mocking.
• Avoid blocking calls; perform DB access asynchronously.

Security and Production Rules

• Validate Auth0 tokens (issuer, audience) and verify signature using JWKS with caching.
• Do not log tokens or sensitive claims; redact secrets in logs.
• Enable TLS in all environments and rotate credentials regularly.
• Use environment-based configuration and secret management; avoid hard-coded secrets.
• Apply proper access controls on endpoints and enforce least privilege for roles.

Testing Checklist

• Unit tests for validators, utilities, and token verification logic.
• Integration tests for API endpoints with a test database and mock Auth0 tokens.
• End-to-end tests scaffolded for CI with docker-compose-based services.
• Smoke tests to confirm healthy startup, migrations, and basic CRUD flows.

Common Mistakes to Avoid

• Relying on in-memory DB in development as a substitute for MySQL in production workflows.
• Hard-coding Auth0 credentials or audience values in code or config.
• Skipping token validation for endpoints accidentally or via middleware misconfiguration.
• Blocking I/O in async paths or using non-async DB drivers.

FAQ