Angular Material + FastAPI JWT Auth CLAUDE.md Template

Overview

Direct answer: This CLAUDE.md Template provides a copyable Claude Code starter for building an Angular Material frontend with a FastAPI backend using JWT authentication. It fixes architecture choices, token handling, and a stack-specific project structure you can paste into CLAUDE.md.

The template targets the Angular Material + FastAPI JWT Auth stack and includes concrete rules for authentication, validation, security, testing, and deployment.

When to Use This CLAUDE.md Template

• Starting a new project with Angular Material UI and a FastAPI backend using JWT authentication.
• Need a copyable Claude Code starter to enforce stack-specific security and structure.
• Seeking a predefined project structure, validation, and deployment rules for auth-enabled apps.

Copyable CLAUDE.md Template

# CLAUDE.md
Project Role: Frontend-Backend Security Engineer for Angular Material + FastAPI JWT Auth
Architecture Rules:
- Use FastAPI as the API layer with JWT-based authentication (access + refresh tokens)
- Use Angular Material components for the login and protected views
- Claude Code must be deterministic and idempotent for idempotent endpoints
- Follow a clean separation of concerns between frontend and backend
File Structure Rules:
- Place backend in 'backend/' and frontend in 'frontend/'
- Backend modules under 'backend/app', frontend under 'frontend/src/app'
Authentication Rules:
- Implement OAuth2 with JWT Bearer tokens; refresh tokens via refresh endpoint
- Store access tokens in HttpOnly cookies; allow optional Authorization header if cookies are unavailable
- Enforce strict password hashing (bcrypt) and secure token generation
Database Rules:
- Use PostgreSQL (or SQLite for local dev) with defined migrations
- Enforce foreign keys and proper indices for auth tables
- Do not store plain passwords; only hashed values
Validation Rules:
- Validate all inputs with Pydantic models on backend
- Validate JWT claims (exp, iss, aud) on protected endpoints
- Validate frontend form inputs with Angular reactive forms
Security Rules:
- Use HTTPS in production
- Rotate signing keys; verify issuer and audience
- Prevent token leakage via referrer and CORS protections
Testing Rules:
- Unit tests for token creation, validation, and protected routes
- Integration tests for login, token refresh, and access to protected endpoints
- End-to-end tests for login flow with Angular Material UI
Deployment Rules:
- Dockerize both frontend and backend; docker-compose for dev
- Use environment variables for secrets
- Auto-run migrations on startup
Things Claude Must Not Do:
- Do not implement insecure token storage in localStorage
- Do not disable CSRF protections when using cookies
- Do not hard-code secrets; never log raw tokens

Recommended Project Structure

backend/
  app/
    main.py
    api/
      auth.py
      users.py
    core/
      config.py
      security.py
    models/
      user.py
    schemas/
      user.py
    services/
      auth_service.py
    db/
      migrations/
  tests/
  Dockerfile
  requirements.txt

frontend/
  angular.json
  package.json
  tsconfig.json
  src/
    app/
      auth/
      components/
      services/
      app.module.ts

Core Engineering Principles

• Explicit type definitions and input validation across frontend and backend
• Principle of least privilege for tokens and API access
• Clear separation of concerns between UI and API layers
• Defensive programming with strong error handling and retry awareness
• Idempotent design for state-changing endpoints and deterministic tests

Code Construction Rules

• Backend language: Python 3.11+, FastAPI, Pydantic
• Frontend language: TypeScript, Angular 16+ with Angular Material
• JWT signing algorithm: HS256 with a strong secret from environment vars
• Token handling: Access token short-lived; refresh token rotated and stored securely
• Password hashing: bcrypt with salted hashes
• Use Python JOSE or PyJWT for token creation and verification
• Implement OAuth2PasswordBearer for protected endpoints on backend
• Define Pydantic models for request/response payloads and validation schemas
• Use dependency injection for auth and token validation
• Provide clear error messages but avoid leaking sensitive data
• Documentation: type hints and OpenAPI docs for auth endpoints

Security and Production Rules

• Use HTTPS; configure TLS in production
• HttpOnly cookies for tokens; secure cookie flags in production
• Rotate JWT signing keys; implement simple key rollover strategy
• Validate issuer (iss) and audience (aud) in both token creation and verification
• Enable CORS with strict origins; disable insecure cross-origin requests
• Implement token revocation or short-lived tokens with refresh strategy
• Implement logging, monitoring, and alerting for failed auth attempts

Testing Checklist

• Unit tests for token creation/verification and password hashing
• Integration tests for login, refresh, and protected routes
• End-to-end tests for the login flow in the Angular Material UI
• Static type checks and linting; run pytest and ng test
• Security scanning and dependency audit in CI

Common Mistakes to Avoid

• Storing tokens in localStorage or insecure storage
• Not validating JWT claims or ignoring exp/iss/aud
• Using weak secrets or leaking tokens in logs
• Disabling CSRF protections when using cookies
• Ignoring proper password hashing and peppering strategies

FAQ

What is this CLAUDE.md Template for?

A copyable Claude Code starter for building an Angular Material frontend with a FastAPI backend using JWT authentication.

Which stack does this template cover?

Angular Material on the frontend and FastAPI on the backend with JWT-based authentication.

How do I customize the JWT secret and expiration?

Configure environment variables in the backend (JWT_SECRET, ACCESS_TOKEN_EXPIRES, REFRESH_TOKEN_EXPIRES) and use them in token creation.

How do I run and test locally?

Run the frontend and backend separately (ng serve and uvicorn) and run integration tests for login, token refresh, and access to protected endpoints.

What about security considerations?

Use HTTPS, HttpOnly cookies or secure storage for tokens, rotate signing keys, validate claims, and implement token revocation as needed.