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

Related implementation resources: AI Use Case for Software Agencies Using Github Copilot To Accelerate Boilerplate Code Generation for New Client Mvps and Skill files and CLAUDE.md templates to enforce frontend design consistency in production AI workflows.

FAQ