CLAUDE.md Template: FastAPI + DynamoDB + AWS Cognito + Pydantic v2 + Boto3 Mapper Engine

Overview

This CLAUDE.md template page showcases a copyable CLAUDE.md template for building a secure FastAPI API backed by DynamoDB, authenticated via AWS Cognito, and modeled with Pydantic v2. It leverages a Boto3 Mapper Engine to map DynamoDB items to Pydantic models, enabling a type-safe, production-ready API scaffold. The page includes a direct, paste-ready CLAUDE.md block and stack-specific implementation constraints for Claude Code.

Direct answer: Use this CLAUDE.md Template to generate a FastAPI service with DynamoDB persistence, Cognito authentication, and Pydantic v2 data contracts using a Boto3 Mapper Engine.

When to Use This CLAUDE.md Template

• You are building a FastAPI API that persists data in DynamoDB and requires Cognito-based authentication.
• You want strict, type-safe data models using Pydantic v2 and seamless DynamoDB mapping via a Boto3 Mapper Engine.
• You need a repeatable project skeleton with clear architecture and validation rules for Claude Code automation.

Copyable CLAUDE.md Template

# CLAUDE.md

Project Role: Full-Stack AI Engineer for a FastAPI API backed by DynamoDB, with AWS Cognito authentication, using Pydantic v2 models and a Boto3 Mapper Engine.

Architecture rules:
- Layered architecture: API layer (FastAPI) → Service layer → Data Access layer (DynamoDB via Boto3 Mapper Engine) → Mapping layer (Pydantic v2 models).
- All input/output data contracts must be defined as Pydantic v2 models in app/models/schemas.py and mapped to DynamoDB items via the mapper.
- Use Cognito JWT tokens for all protected endpoints; verify tokens in middleware and attach user context to requests.
- Avoid direct DynamoDB writes from client code; access via service layer with proper validation.
- All DB reads must consider eventual consistency updates; handle retries with exponential backoff.

File structure rules:
- app/
  - main.py
  - api/
    - v1/
      - endpoints.py
  - models/
    - schemas.py
  - services/
    - item_service.py
  - db/
    - dynamodb_client.py
  - auth/
    - cognito.py
  - mapper/
    - boto3_mapper.py
  - config/
    - settings.py
- tests/
- requirements.txt
- Dockerfile

Authentication rules:
- Require Authorization header with a valid Cognito JWT.
- Validate iss, aud, exp, token_use claims; ensure user is enabled in Cognito.
- Attach user_id from JWT to request context for downstream logic.

Database rules:
- DynamoDB table names come from environment DYNAMODB_TABLE_NAME.
- Primary key schema uses partition key 'pk' and sort key 'sk'.
- Use TTL attribute for expiring items where appropriate.
- Use the Boto3 Mapper Engine to translate DynamoDB items to Pydantic v2 models; enforce types during mapping.

Validation rules:
- All inputs validated via Pydantic v2 models; reject invalid payloads with 422 errors.
- Enforce strict typing on responses to maintain contract stability.

Security rules:
- Do not log sensitive payloads; redact tokens and secrets in logs.
- Use TLS/HTTPS in production; do not expose credentials in code or env files.
- Enable DynamoDB encryption at rest and Cognito token revocation checks where applicable.

Testing rules:
- Unit tests for Pydantic schemas and mapping logic.
- Integration tests for Cognito authentication flow and DynamoDB interactions.
- Use a local DynamoDB instance or mock mapper for deterministic tests.

Deployment rules:
- Containerize with Docker; run uvicorn via a production-grade ASGI server (gunicorn + uvicorn workers) for deployment.
- Environment variables: AWS_REGION, DYNAMODB_TABLE_NAME, COGNITO_USER_POOL_ID, COGNITO_CLIENT_ID, etc.
- CI should run lint, unit tests, and integration tests; secrets must be injected via CI secrets, not stored in repo.

Things Claude must not do:
- Do not hard-code credentials or secrets in code or CLAUDE.md templates.
- Do not bypass Cognito authentication or create short-lived tokens without validation.
- Do not access DynamoDB tables outside the intended schema or perform bulk deletions in production.
- Do not assume Prisma, Mongoose, or unrelated ORMs; use DynamoDB mapper and Pydantic v2 only.

Recommended Project Structure

app/
  main.py
  api/
    v1/
      endpoints.py
  models/
    schemas.py
  services/
    item_service.py
  db/
    dynamodb_client.py
  auth/
    cognito.py
  mapper/
    boto3_mapper.py
  config/
    settings.py
tests/
infra/

Core Engineering Principles

• Strict type contracts via Pydantic v2; all data shapes are explicit and validated.
• Single responsibility and clear separation of concerns across layers.
• Idempotent endpoints and safe retries for DynamoDB interactions.
• Deterministic mapping between DynamoDB items and domain models.
• Config-driven behavior with environment-first configuration.

Code Construction Rules

• All endpoints defined in app/api/v1 with explicit input/output schemas.
• Use Pydantic v2 BaseModel for all request/response models.
• Map DynamoDB items to Pydantic models via a dedicated Boto3 Mapper Engine wrapper.
• JWT validation must be performed by a reusable Cognito middleware.
• Environment-driven configuration; avoid hard-coded values.
• Endpoint handlers should delegate to services; keep controllers thin.
• Do not bypass type validation for any external input.

Security and Production Rules

• Authorize all protected routes with Cognito tokens; verify token claims server-side.
• Use DynamoDB encryption at rest and enable proper access policies with least privilege.
• Never log full tokens or secrets; redact sensitive fields in logs.
• Use TLS in all network communications; rotate credentials regularly.
• Keep dependencies up-to-date and pinned; audit dependencies for CVEs.

Testing Checklist

• Unit tests for all Pydantic schemas and mapper functions.
• Integration tests verifying Cognito token validation and DynamoDB read/write paths (use LocalStack or a mocked mapper).
• End-to-end tests for a typical create/get flow with authentication.
• CI/CD checks for lint, tests, and security scanning.

Common Mistakes to Avoid

• Relying on plain dictionaries instead of Pydantic v2 models for validation.
• Hard-coding credentials or client IDs in code or CLAUDE.md blocks.
• Skipping token validation or trusting tokens without signature verification.
• Over-fetching data or bypassing the mapper layer when reading/writing DynamoDB.

FAQ

• Q: How do I authenticate requests with Cognito in FastAPI?
• A: Validate the JWT in the Authorization header against the Cognito JWKS, verify iss/aud, and attach user context to the request.
• Q: How do I map DynamoDB items to Pydantic v2 models?
• A: Use the Boto3 Mapper Engine wrapper to convert DynamoDB maps to Pydantic v2 BaseModel instances, with explicit field types and validators.
• Q: How to configure the environment for local development?
• A: Use a local DynamoDB instance or LocalStack; provide DYNAMODB_TABLE_NAME, COGNITO_* values via environment variables.
• Q: How do I test Cognito JWT validation?
• A: Use test tokens issued by a dev Cognito user pool or mock JWKS in unit tests; assert correct 401 responses for invalid tokens.
• Q: How should I deploy this stack to AWS?
• A: Dockerize the FastAPI app, deploy with a production ASGI server, configure IAM roles, and use CloudFormation or Terraform for infrastructure.