CLAUDE.md Template: Rust Actix-Web + SQLite + Better-Auth Bridges + Diesel ORM

Overview

A CLAUDE.md template for Rust with Actix-Web, SQLite, Better-Auth Bridges, and Diesel ORM provides a copyable Claude Code blueprint that scaffolds a production-ready backend pipeline. It targets a small-to-medium API service backed by a local SQLite database, using Diesel for migrations and ORM, Actix-Web for the HTTP layer, and a Better-Auth Bridges pattern to handle authentication tokens. This page is a copyable CLAUDE.md Template you can paste directly into CLAUDE.md to guide Claude Code through a complete Rust stack.

Direct answer: This CLAUDE.md Template yields a runnable blueprint for a Rust Actix-Web + SQLite + Better-Auth Bridges + Diesel stack, with concrete project structure, rules, and security guidance.

When to Use This CLAUDE.md Template

• Starting a Rust API project with Actix-Web and SQLite where you want a reproducible data layer via Diesel ORM.
• Prototyping authentication flows using a Better-Auth Bridges pattern without a full external auth provider.
• Delivering a paste-ready CLAUDE.md Template that a teammate can adapt quickly for similar stacks.

Copyable CLAUDE.md Template

# CLAUDE.md

Project role: You are a senior Rust backend engineer tasked with delivering a secure, production-ready Actix-Web API backed by SQLite, using Diesel ORM and a Better-Auth Bridges authentication pattern. Claude, follow the rules below to implement the stack.

Architecture rules:
- HTTP layer: Actix-Web 4.x with a RESTful API design.
- Data access: Diesel ORM with SQLite, migrations in diesel/migrations.
- Auth: Better-Auth Bridges for token-based authentication (JWT-like tokens), with a pluggable policy for access control.
- Environment: Reads config from environment variables; do not hardcode secrets.
- Logging: Structured logging using the log crate; redact sensitive fields in production.
- Testing: Unit tests for handlers/models; integration tests hitting an in-memory SQLite DB when feasible.
- Deployment: Build a small container image; ensure the container runs migrations on startup.
- Observability: Expose minimal health checks and a bindable port.

File structure rules:
- Keep code under src/, migrations under diesel/migrations/ and migrations/; include a config module.
- Use modules: handlers/, models/, routes/, middleware/, config/
- Do not mix business logic with HTTP handlers; separate concerns clearly.

Authentication rules:
- Use Better-Auth Bridges to issue and verify tokens; validate token claims on each request.
- Do not accept tokens from untrusted sources; verify signature and expiry on every protected endpoint.
- Store password hashes (bcrypt) and never plaintext passwords.

Database rules:
- SQLite as the local data store; diesel migrations manage schema.
- Use prepared statements via Diesel; never interpolate raw SQL strings.
- Provide a simple users table with id, username, password_hash, created_at, updated_at.

Validation rules:
- Validate input payloads at the API boundary; use Actix extractors with proper type validation.
- Return standardized error payloads with HTTP status codes.

Security rules:
- Disable CORS in production or restrict origins; allow only trusted origins.
- Ensure TLS in production; avoid exposing credentials via responses.
- Sanitize error messages to avoid leaking internal details.

Testing rules:
- Unit-test models and utilities; integration-test endpoints with a test SQLite database.
- Include tests for authentication flows and authorization checks.
- Run migrations before integration tests; pin Diesel CLI version in dev.

Deployment rules:
- Build a minimal, reproducible Docker image; run database migrations on startup.
- Use environment-based configuration for DB path and secret keys.
- Enable health checks and log startup/shutdown events.

Things Claude must not do:
- Do not hardcode secrets; do not bypass authentication checks.
- Do not use raw SQL for user data manipulation; do not bypass Diesel for data access.
- Do not assume production DB is SQLite; provide a config switch for Postgres if needed.

Recommended Project Structure

project-root/
├── Cargo.toml
├── Diesel.toml
├── diesel/                # Diesel CLI setup and migrations
│   └── migrations/
├── migrations/            # SQLite migrations for initial schema
├── src/
│   ├── main.rs              # App bootstrap, server start, routes
│   ├── config.rs            # AppConfig parsing from env
│   ├── db.rs                # DB pool and connection helpers
│   ├── models.rs            # DB models and Diesel schema
│   ├── schema.rs            # Diesel schema bindings
│   ├── routes/
│   │   └── mod.rs           # Route configuration
│   ├── handlers/
│   │   └── auth.rs            # Auth-related handlers
│   └── middleware/
│       └── auth.rs            # Token verification and guards
├── config/
│   └── settings.rs          # Centralized settings (ENV)
├── .env.example              # Example env values (not committed secrets)
├── Dockerfile
└── README.md

Core Engineering Principles

• Explicit boundaries: separate HTTP, business logic, and data access layers.
• Type-safe data handling: leverage Diesel DSL to prevent SQL injection and runtime errors.
• Config over hard-coded values: read from environment with sensible defaults.
• Repeatable builds: migrations, CLI tooling, and containerized deployments must be deterministic.
• Security by default: enforce token validation, least privilege, and proper error handling.

Code Construction Rules

• Use Actix-Web 4.x with App::new().service(...) and App::wrap for middleware.
• Prefer Diesel ORM with SQLite for development; switch to Postgres in production via DSN config.
• Token-based authentication via Better-Auth Bridges; validate tokens on protected routes.
• All DB calls must go through Diesel; avoid raw SQL strings or string concatenation.
• Environment-driven configuration for ports, DB paths, and secrets.
• Tests must be runnable in CI with a disposable SQLite DB or an in-memory-like setup.
• Do not use unsafe blocks for business logic; keep unsafe only in low-level bindings if absolutely required.

Security and Production Rules

• Enable TLS termination at the reverse proxy; do not expose HTTP endpoints directly in prod.
• Hash passwords with bcrypt/argon2; store only salted hashes.
• Validate all inputs and enforce strict token audience/issuer checks in Better-Auth Bridges.
• Guard against SQL injection by using Diesel query DSL and parameterized queries.
• Enable logging with redaction of secrets; avoid logging full tokens or passwords.

Testing Checklist

• Unit tests for models and utilities; integration tests for endpoints and auth flows.
• Migration tests: ensure diesel migrations apply cleanly and rollback if needed.
• End-to-end tests for token issuance, validation, and protected routes.
• CI should run cargo test and cargo diesel CLI checks where applicable.
• Production readiness: test with a realistic SQLite file and ensure migrations run on startup.

Common Mistakes to Avoid

• Mixing business logic inside route handlers; avoid logic layering violations.
• Storing plaintext credentials or hardcoded secrets in code or repository.
• Skipping migrations or bypassing Diesel for schema changes.
• Overcomplicating authentication flow; keep the bridge pattern simple and auditable.
• Neglecting input validation leading to brittle APIs.

FAQ