Angular Material + FastAPI Auth0 CLAUDE.md Template

Overview

CLAUDE.md template for Angular Material + FastAPI + Auth0 demonstrates how to scaffold a secure, production-ready full-stack starter. This page is a copyable CLAUDE.md template that you can paste into Claude Code to generate the project guidelines and boilerplate for this stack.

Direct answer summary: This CLAUDE.md template provides a complete starter with explicit rules for architecture, file structure, authentication, validation, security, testing, deployment, and failure safety for an Angular Material frontend and a FastAPI backend secured by Auth0.

When to Use This CLAUDE.md Template

• Starting a new Angular Material frontend integrated with a FastAPI backend behind Auth0
• Standardizing Claude Code outputs for this stack across teams
• Kickstarting secure authentication flows with PKCE and access token validation

Copyable CLAUDE.md Template

# CLAUDE.md
Project role: You are Claude Code, a starter assistant for the Angular Material + FastAPI + Auth0 stack. Produce a complete CLAUDE.md with concrete, copy-pasteable instructions for this stack.

Architecture rules:
- Frontend: Angular Material application with a clean material theme, lazy-loaded modules, and AOT build.
- Backend: FastAPI service exposing REST endpoints, Pydantic models, and dependency injection.
- Auth: Auth0 as the identity provider; validate and authorize JWTs in the backend; PKCE for SPA.

File structure rules:
- Keep frontend and backend in separate top-level directories
- Do not mix UI and API code; place shared types in a shared folder
- Use environment-controlled configuration with .env files

Authentication rules:
- Use Auth0 for login and obtaining tokens
- Validate JWTs on protected routes in FastAPI using a trusted JWKS
- Use the access token for API calls; do not rely on ID tokens for API auth

Database rules:
- Use PostgreSQL for persistent storage
- Use SQLAlchemy ORM with Alembic migrations
- Do not store plaintext passwords; rely on Auth0 for authentication

Validation rules:
- All input models must be Pydantic models with explicit field types
- Validate request bodies and query params with clear error messages
- Enforce strict typing and runtime validation

Security rules:
- Do not expose secret keys in code
- Enforce HTTPS in production
- Configure CORS to allow only trusted origins
- Use secure cookies for session state if needed (prefer token-based auth)

Testing rules:
- Frontend tests with Jasmine/Karma or Jest
- Backend tests with pytest and httpx
- Include end-to-end tests for login and protected endpoints

Deployment rules:
- Use Docker Compose to run frontend and backend with tokens loaded from environment
- Provide a simple CI workflow for building and testing
- Document environment variables in a .env.sample

Things Claude must not do:
- Do not generate plaintext credentials
- Do not embed Auth0 client secrets
- Do not assume a particular cloud provider unless specified
- Do not bypass PKCE for SPA authentication

Recommended Project Structure

frontend/
  angular-material-app/
    src/
      app/
        components/
        pages/
        services/
        app.module.ts
      index.html
      styles.css
    angular.json
    package.json

backend/
  fastapi-auth0/
    app/
      main.py
      api/
        v1/
          endpoints/
          models/
      core/
        config.py
      auth/
        auth0.py
    requirements.txt
    Dockerfile

infra/
  docker-compose.yml
  .env.example

Core Engineering Principles

• Explicit and copyable Claude Code: outputs must be deterministic and reusable.
• Stack fidelity: follow the Angular Material + FastAPI + Auth0 architecture exactly.
• Security first: never expose secrets, validate tokens, enforce CORS and HTTPS.
• Testability: include unit, integration, and deployment checks.
• Documentation: include copyable CLAUDE.md blocks and clear rules.

Code Construction Rules

• Use TypeScript interfaces for frontend data shapes; Pydantic models for backend
• Use Auth0 JWT validation on backend with JWKS endpoint
• Environment-driven configuration; never hardcode secrets
• Follow a modular architecture: feature modules for frontend, API routes for backend
• Keep CLAUDE.md blocks small and actionable

Security and Production Rules

• Enable CORS for trusted origins only
• Use HTTPS in production; deploy behind a reverse proxy
• Validate JWTs with proper audience and issuer
• Do not store access tokens in local storage; prefer httpOnly cookies if possible

Testing Checklist

• Frontend unit tests with Jest or Karma
• Backend unit tests with pytest and httpx
• Integration tests for login flow and protected endpoints
• CI workflow to run tests and build artifacts

Common Mistakes to Avoid

• Assuming Auth0 is optional; ensure proper token verification
• Hardcoding secrets in repository
• Skipping PKCE for SPA authentication

FAQ

Is Auth0 required?

Yes, this starter uses Auth0 for authentication and token validation on the backend. You can adapt to another provider, but it will require changes.

How do I run the project?

Run docker-compose up in the project root after configuring environment variables.

Where should secrets be stored?

Store secrets in environment variables or a secret manager; never commit secrets to version control.

Can I replace Angular Material with another UI library?

You can substitute a different UI library, but keep the stack structure and token validation approach.

How is JWT validated in FastAPI?

JWTs are validated against Auth0's JWKS with configured audience and issuer in FastAPI.