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.

Related implementation resources: AI Use Case for Software Agencies Using Github Copilot To Accelerate Boilerplate Code Generation for New Client Mvps and Implementing Parameterized Testing Matrices for Wide Input Coverage in Production AI.

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.