CLAUDE.md Template: FastAPI + Neon Postgres + Auth0 + Tortoise ORM Engine Layout

Overview

Direct answer style summary: This CLAUDE.md Template delivers a concise, copyable Claude Code block for a production ready FastAPI service backed by Neon Postgres with Auth0 authentication and a Tortoise ORM engine layout. Paste the CLAUDE.md block into your repo to bootstrap the stack with consistent structure, security practices, and testability.

When to Use This CLAUDE.md Template

• You are building a production API with FastAPI and need a Neon Postgres backed data store
• You require Auth0 for authentication and JWT validation on API endpoints
• You prefer a Tortoise ORM based data access layer with async support
• You want a ready to paste CLAUDE.md template that enforces architecture, testing, and deployment rules

Copyable CLAUDE.md Template

# CLAUDE.md
Project role: Senior Backend Engineer for a FastAPI + Neon Postgres + Auth0 + Tortoise ORM stack
Stack: FastAPI, Neon Postgres, Auth0, Tortoise ORM
Architecture rules:
  - Build a modular backend with clear boundaries: api, core, db, models, services, and auth
  - All endpoints must be async and respect dependency injection for DB sessions
  - Centralize configuration via environment based settings
  - Use a single source of truth for user identity and permissions
File structure rules:
  - app/
    - api/
      - v1/
        - endpoints/
    - core/
      - config.py
      - security.py
    - db/
      - tortoise_config.py
    - models/
    - services/
    - auth/
  - tests/
  - migrations/
Authentication rules:
  - Validate Auth0 JWTs using RS256 with issuer and audience checks
  - Validate token signature, expiration, and claimed scopes/roles
  - Map scopes to FastAPI dependencies for authorization
Database rules:
  - Neon Postgres connection via DATABASE_URL with TLS
  - Use Tortoise ORM models with async queries
  - Enable and manage migrations via tortoise migrations tooling
Validation rules:
  - Use Pydantic models for request and response validation
  - Enforce strict typing and input validation
Security rules:
  - Do not log raw tokens or secrets
  - Do not expose secrets in code or config files
  - Enforce HTTPS in production and tight CORS in dev
  - Rotate credentials and use environment scoped secrets
Testing rules:
  - Unit tests for models and utilities
  - Integration tests for endpoints with mock Auth0 tokens
  - End to end tests with a test Neon Postgres instance
Deployment rules:
  - Dockerfile and docker-compose for local dev
  - Prepare Kubernetes manifests or cloud run configs for deployment
Things Claude must not do:
  - Do not bypass authentication or authorization checks
  - Do not generate raw SQL via string concatenation
  - Do not bypass migrations or rely on in memory schemas

Recommended Project Structure

project/
  app/
    main.py
    api/
      v1/
        endpoints/
    core/
      config.py
      security.py
    db/
      tortoise_config.py
    models/
    services/
    auth/
  tests/
  requirements.txt
  Dockerfile
  docker-compose.yml

Core Engineering Principles

• Clear separation of concerns and predictable boundaries
• Typed interfaces and contract driven development
• Configuration as code with environment based settings
• Security by default and verifiable authentication
• Testability and observable behavior through tests and logging

Code Construction Rules

• Use FastAPI style path operations with async def
• Model API contracts with Pydantic and enforce validation
• Access Neon Postgres through Tortoise ORM models with async queries
• Authenticate requests using Auth0 JWTs and verify issuer audience and scopes
• Keep secrets out of code and inject via environment variables
• Write modular, reusable components and avoid tight coupling
• Follow consistent naming conventions and folder structure
• Do not embed sensitive data or secrets in code or migrations

Security and Production Rules

• Validate every access token and enforce scope based access
• TLS enabled connections to Neon Postgres and encrypted secrets storage
• Audit logs for authentication events and errors while not storing raw tokens
• Limit CORS, implement rate limiting when public endpoints exist
• Automated tests and CI checks for security regressions

Testing Checklist

• Unit tests for models and validators
• Integration tests for routes protected by Auth0 tokens
• Migration tests and data seeding checks
• End to end tests with a test Neon Postgres instance
• CI pipeline runs linting, type checking, tests, and coverage

Common Mistakes to Avoid

• Skipping authentication or lax authorization checks
• Hardcoding secrets or credentials in code or migrations
• Forgetting to close database connections or mismanaging sessions
• Not validating JWT claims or ignoring issuer/audience validation
• Neglecting migrations when evolving the data model

FAQ

What is the CLAUDE.md Template for this stack?

A copyable Claude Code block and project layout tailored for FastAPI + Neon Postgres + Auth0 + Tortoise ORM.

How do I customize Auth0 configuration?

Modify issuer, audience, and JWKS endpoint in the config, and wire token validation in the security module.

How can I run this locally?

Run the dev stack via docker-compose with a local Neon Postgres container and a mock Auth0 tenant for testing tokens.

How do migrations work with Tortoise ORM?

Define models in app/models, run tortoise migrations, and use generate_schemas in development for quick iterations.

How do I verify JWT tokens in endpoints?

Parse and verify the JWT using RS256, check audience and issuer, and enforce scopes via dependencies.