CLAUDE.md Template: Rust (Actix-Web) + Neon Postgres + Auth0 + SQLx Async

Overview

Direct answer: This CLAUDE.md Template page provides a ready-to-paste Claude Code block for a Rust (Actix-Web) API that uses Neon Postgres as the database, Auth0 for authentication, and SQLx for asynchronous data access. Paste the code block below into a CLAUDE.md file to bootstrap a secure, scalable backend.

The template is crafted for developers building production Rust services, emphasizing type-safety, async DB access with SQLx, and robust JWT-based authentication via Auth0.

When to Use This CLAUDE.md Template

• Starting a new Actix-Web API that relies on Neon Postgres for storage.
• Integrating Auth0 to authenticate API requests and issue/verify JWTs.
• Adopting SQLx for compile-time checked, asynchronous queries against Postgres.
• Setting up a clean, testable architecture with clear separation of concerns (routes, handlers, models, services).
• Needing a paste-ready CLAUDE.md template to accelerate onboarding of new contributors.

Copyable CLAUDE.md Template

# CLAUDE.md

Project role: Backend Rust engineer building an Actix-Web API that uses Neon Postgres as the database, Auth0 for authentication, and SQLx for async data access.

Architecture rules:
- Use Actix-Web 4.x; modularize into routes, handlers, and services with AppState for shared resources.
- Database access via SQLx with the postgres runtime; enable compile-time checks (sqlx::query!, query_as!, etc.).
- Neon Postgres is the primary data store; migrations live in migrations/ and are executed before service startup.
- Authentication is handled by Auth0; verify JWTs in a dedicated middleware; require audience and issuer validation.
- Use tokio as the async runtime; avoid blocking calls on the async path.
- Keep secrets out of code; load from environment variables or a secrets manager.

File structure rules:
- src/
  - main.rs
  - config.rs
  - routes/mod.rs
  - routes/{resource}.rs
  - handlers/{resource}.rs
  - models/{resource}.rs
  - services/{resource}.rs
  - middleware/{middleware}.rs
- migrations/
- tests/
- Dockerfile
- docker-compose.yml
- .env.example

Authentication rules:
- Validate JWTs issued by your Auth0 tenant; enforce RS256, audience, and issuer checks.
- Tokens are not stored; they are presented with each request in the Authorization header.
- Roles/permissions from JWT claims can be checked in route guards.

Database rules:
- Use Neon Postgres with a SQLx connection pool; configure max_connections via env.
- All queries must be parameterized; avoid string interpolation for user input.
- Use migrations in migrations/; track versions and ensure migrations run before app startup.
- Define models with FromRow implementations for sqlx to map to Rust types.

Validation rules:
- Validate input using Serde deserialization with explicit validation where needed.
- Normalize and sanitize input before querying the database.
- Return granular but safe error messages.

Security rules:
- Enforce TLS in deployment; disable HTTP in production; enable HSTS.
- Do not log sensitive fields; sanitize error output in production.
- Use proper CORS settings and only allow origin(s) you control.

Testing rules:
- Unit tests for validators and small services.
- Integration tests for routes with a test Neon Postgres instance or a containerized test DB.
- Verify JWT auth path with mock tokens in tests.
- Include tests for SQLx queries with parameterized inputs.

Deployment rules:
- Build with cargo build --release; produce a small runtime image if using Docker.
- Use a multi-stage Dockerfile; copy the compiled binary into a minimal runtime image.
- Provide a docker-compose.yml for local development and a Kubernetes manifest for deployment if needed.

Things Claude must not do:
- Do not bypass authentication or skip audience/issuer validation.
- Do not generate raw SQL with string concatenation for user input.
- Do not hardcode database credentials or secret keys in code.
- Do not assume Neon Postgres specifics without explicit config; use environment-driven settings.

Recommended Project Structure

my-api/
├── src/
│   ├── main.rs
│   ├── config.rs
│   ├── routes/
│   │   ├── mod.rs
│   │   └── user.rs
│   ├── handlers/
│   │   ├── mod.rs
│   │   └── user.rs
│   ├── models/
│   │   └── user.rs
│   ├── services/
│   │   └── auth.rs
│   └── middleware/
│       └── auth_middleware.rs
├── migrations/
├── tests/
├── Dockerfile
├── docker-compose.yml
└── .env.example

Core Engineering Principles

• Type-safety and compile-time guarantees with SQLx macros.
• Clear separation of concerns across routes, handlers, models, and services.
• Security-first by default: JWT authentication, secure storage of secrets, and validated inputs.
• Observability through structured logs and traces.
• Deterministic, testable code with solid error handling paths.

Code Construction Rules

• Prefer SQLx for all database interactions; use query!, query_as!, and related macros for compile-time checks.
• Implement a dedicated Auth middleware to verify Auth0 JWTs and attach claims to request extensions.
• Avoid blocking calls in Actix-Web handlers; keep all I/O asynchronous.
• Store configuration in environment variables and load them at startup with validation.
• Use parameterized queries; never interpolate user input into SQL strings.
• Structure code to facilitate testing (dependency injection for DB pools and auth guards).

Security and Production Rules

• Enable TLS termination at the edge or via a reverse proxy; disable insecure protocols.
• Rotate secrets; do not commit secrets to version control.
• Validate all inputs; sanitize outputs to prevent injection attacks.
• Limit database privileges for the API user to the minimum required (least privilege).
• Use proper CORS rules and secure cookies for session-related data where applicable.

Testing Checklist

• Unit test validators and small service functions.
• Integration tests for Actix routes with a test Neon Postgres instance.
• End-to-end tests covering authentication with mock Auth0 tokens.
• Test migrations and ensure schema consistency with SQLx migrate.
• Check deployment readiness with cargo test -- --nocapture in CI.

Common Mistakes to Avoid

• Assuming JWTs are trusted without validating issuer and audience.
• Using string concatenation in SQL; leading to SQL injection risks.
• Hardcoding database connection details in code or containers.
• Overlooking proper error handling and returning sensitive data in errors.

FAQ

What stack is this CLAUDE.md Template for?

Rust with Actix-Web, Neon Postgres, Auth0 authentication, and SQLx for async data access.

How do I verify Auth0 tokens in Actix-Web?

Use a middleware that validates JWTs against Auth0's JWKS using RS256 and checks audience/issuer.

Where do migrations go?

Migrations live in the migrations/ directory and are executed before the app starts (via sqlx migrate).

Should I store secrets in the codebase?

No. Use environment variables or a secrets manager; never commit secrets.

Can I deploy this template to production?

Yes, with TLS, proper secret management, and careful configuration of Neon Postgres and Auth0 settings.