CLAUDE.md Template: Rust (Axum) + PostgreSQL + Custom JWT Verification + SQLx Raw Type-Safe Client

Overview

The CLAUDE.md template is a copyable Claude Code recipe designed for Rust (Axum) + PostgreSQL + Custom JWT Verification + SQLx Raw Type-Safe Client. It enables you to paste a ready-to-run CLAUDE.md block into Claude Code to generate a secure, type-safe API layer.

Direct answer: This template provides a complete CLAUDE.md block to drive a Rust Axum API with PostgreSQL using SQLx compile-time checks and a custom JWT verification flow.

When to Use This CLAUDE.md Template

• When building a Rust API service using Axum that talks to PostgreSQL.
• When you want compile-time SQLx queries for compile-time safety (query! / query_as!).
• When a custom JWT verification middleware is required (RS256/HS256) with claims validated against a config.
• When you need a copyable CLAUDE.md block to generate consistent code and tests.

Copyable CLAUDE.md Template

# CLAUDE.md
Project: Rust API (Axum) + PostgreSQL + Custom JWT Verification + SQLx Raw Type-Safe Client
Role: You are Claude Code, tasked with producing a secure, maintainable Rust backend using Axum, SQLx with compile-time checks, and a custom JWT verification flow.

Architecture rules:
- Use Axum as the HTTP framework and tower layers for middleware.
- Use PostgreSQL as the data store.
- Use SQLx with compile-time checks (query!, query_as!, sqlx::query) for all raw SQL access.
- Implement a dedicated JWT verification layer (middleware) that validates tokens via a configurable verifier (RS256 or HS256).
- Favor raw SQL with strong type-mapping over ORM abstractions. Map results into explicit Rust structs.

File structure rules:
- src/main.rs
- src/router.rs
- src/handlers/mod.rs
- src/handlers/auth.rs
- src/handlers/user.rs
- src/db/mod.rs
- src/db/postgres.rs
- src/models.rs
- Cargo.toml
- .env.example

Authentication rules:
- Accept Authorization: Bearer <token> header.
- Validate JWT using a public key (RS256) or shared secret (HS256) from environment/config.
- Attach validated claims to request extensions for downstream handlers.
- Rotate keys and validate issuer/audience when configured.

Database rules:
- Connect to PostgreSQL via a pool (sqlx::postgres::PgPool).
- Use query! and query_as! with parameterized inputs to prevent SQL injection.
- Use transactions for write operations when needed.
- Avoid string concatenation for queries; use placeholders and the builder API when dynamic.

Validation rules:
- Validate all input data with strong types; avoid serde defaulting from missing fields.
- Return structured errors with clear messages but avoid leaking secrets.

Security rules:
- Do not log sensitive payloads or tokens.
- Do not bypass TLS; require HTTPS in production.
- Do not embed secrets in code; use environment variables or secret management.
- Do not expose raw SQL to clients or stack traces.

Testing rules:
- Unit test validation helpers and JWT verification logic.
- Integration test the Axum routes with a test PostgreSQL instance (or dockerized).
- Include a small seeding script for test data.

Deployment rules:
- Build in release mode with cargo build --release.
- Use a Dockerfile to containerize the app with a multi-stage build.
- Environment variables: DATABASE_URL, JWT_PUBLIC_KEY, JWT_ISSUER, JWT_AUDIENCE, APP_PORT.
- Health checks and readiness probes in container orchestration.

Things Claude must not do:
- Do not bypass authentication or return tokens directly.
- Do not use unsafe blocks without justification.
- Do not generate SQL via string concatenation from user input.
- Do not rely on an ORM to hide SQL behavior; prefer explicit SQL for clarity and safety.

Recommended Project Structure

src/
├── main.rs
├── router.rs
├── handlers/
│   ├── mod.rs
│   ├── auth.rs
│   └── user.rs
├── db/
│   ├── mod.rs
│   └── postgres.rs
├── models.rs
├── config.rs
└── lib.rs (optional)

Core Engineering Principles

• Explicit typing and compile-time checks across the stack.
• Security-first design: validate tokens, parameterized queries, minimal blast radius.
• Clear separation of concerns between routing, data access, and domain models.
• Deterministic behavior with well-scoped errors and robust tests.

Code Construction Rules

• Use SQLx for raw SQL with compile-time checks (query!, query_as!).
• Wrap DB calls in a reusable repository pattern with proper error mapping.
• Authenticate every protected endpoint using a middleware that stores claims in request extensions.
• Prefer small, composable handlers; avoid long monolithic functions.
• Do not use unwrap/expect in production code paths; return Result errors.
• Do not embed secrets in code; load from environment variables.

Security and Production Rules

• Always verify JWTs with the configured public key or secret.
• Use parameterized SQL and avoid string concatenation.
• Encrypt sensitive data at rest when appropriate; use TLS in transit.
• Rotate keys; support key rollover without downtime.

Testing Checklist

• Unit tests for validation and JWT verification logic.
• Integration tests for Axum routes with a test PostgreSQL instance.
• Tests cover success and failure paths for authentication, data access, and error handling.

Common Mistakes to Avoid

• Assuming SQLx compile-time checks cover all safety; include runtime checks too.
• Hard-coding secrets or keys in code or repository.
• Overusing dynamic SQL without proper parameterization.
• Skipping tests for critical middleware like JWT verification.

FAQ

What is this CLAUDE.md Template for?

A copyable Claude Code recipe for Rust Axum APIs with PostgreSQL and a custom JWT verification flow using SQLx.

Which stack is covered?

Rust (Axum) + PostgreSQL + SQLx (raw, type-safe) + Custom JWT verification.

How do I use this template?

Paste the CLAUDE.md block into Claude Code to generate consistent code for building the API.

Is RS256 or HS256 supported?

Both can be supported via a configurable verifier; configure algorithm in environment and wire verification accordingly.

Where should secrets live?

In environment variables or secret management; never commit secrets in code or CLAUDE.md blocks.