CLAUDE.md Template: Angular Material + FastAPI Clerk Auth

Overview

CLAUDE.md template for Angular Material + FastAPI Clerk Auth provides a copyable CLAUDE.md template that guides Claude Code to scaffold a secure full-stack app with Angular Material UI and a FastAPI backend protected by Clerk authentication. This template covers project roles, architecture constraints, file structure, authentication flows, validation, and deployment rules.

When to Use This CLAUDE.md Template

• Spike or prototype a full-stack app using Angular Material design and Clerk-managed authentication.
• Coordinate frontend and backend teams with a single source of truth for project rules.
• Generate boilerplate code that adheres to security and production best practices for Claude Code.

Copyable CLAUDE.md Template

# CLAUDE.md

Project role
- You are an engineer building an Angular Material frontend with a FastAPI backend secured by Clerk authentication.

Architecture rules
- Monorepo with clear separation between frontend and backend
- Frontend communicates with backend via REST/HTTP or tRPC if used
- Clerk JWTs are validated on backend with Clerk's public keys
- Do not bypass Clerk or store credentials in client-side storage

File structure rules
- frontend/ src/app/ ... angular components
- backend/ app/main.py, app/api/routers, app/models, app/schemas, app/config
- shared/ common utilities

Authentication rules
- Use Clerk for user signup/signin UI on frontend
- Verify Clerk JWT on every protected endpoint
- Require authentication for all user-specific routes

Database rules
- Use PostgreSQL
- Use SQLAlchemy ORM
- Store only app-specific user profile data; Clerk user id is the source of truth

Validation rules
- Pydantic models on backend for request validation
- Server-side validation for all inputs
- Validate Authorization header for protected endpoints

Security rules
- Use HTTPS in all environments
- Do not store sensitive tokens in localStorage
- Rotate API keys periodically
- Enforce CORS for frontend origin

Testing rules
- Backend: unit tests for validators and models; integration tests for auth-enabled endpoints
- Frontend: component and integration tests to cover login flow
- CI should run tests on push to main

Deployment rules
- Use Docker with separate services: frontend and backend
- Environment variables for Clerk keys and DB credentials
- Production build on deployment, not dev server

Things Claude must not do
- Do not bypass Clerk authentication
- Do not generate frontend code without proper Angular templates
- Do not introduce insecure secrets or hard-coded credentials

Recommended Project Structure

frontend/
  angular.json
  package.json
  src/
    main.ts
    index.html
    app/
      app.module.ts
      app.component.ts
      components/
        auth/
        dashboard/
      services/
      styles.css
backend/
  pyproject.toml
  main.py
  app/
    api/
      endpoints/
      routers/
    models/
    schemas/
    config.py
    clerk/
shared/
  common/

Core Engineering Principles

• Security by default: deny by default, require explicit authentication
• Clear contract boundaries between frontend and backend
• Idempotent backend operations and robust input validation
• Observability: structured logging and metrics for auth flows
• Testability: unit and integration tests for both frontend and backend

Code Construction Rules

• Frontend uses Angular Material components for consistent UI
• Backend uses FastAPI with Pydantic models for validation
• Integrate Clerk on frontend for auth flows; on backend verify Clerk JWTs
• Do not implement custom auth unless Clerk integration is proven
• Keep API endpoints RESTful and versioned

Security and Production Rules

• Always use HTTPS and secure cookies; do not expose secrets in code
• Validate Clerk JWTs with public keys; rotate keys
• CSRF protections where applicable; limit CORS origins

Testing Checklist

• Unit tests for validators/models
• Integration tests for auth-protected endpoints
• End-to-end tests for login flow (frontend)
• Deployment smoke tests

Common Mistakes to Avoid

• Skipping Clerk verification on backend endpoints
• Storing tokens insecurely on the frontend
• Ignoring CORS and environment separation

FAQ