CLAUDE.md Template: Angular Material + FastAPI Customer Support App

Overview

Direct answer: This CLAUDE.md template provides a concrete CLAUDE Code blueprint to build a customer support app with an Angular Material frontend and a FastAPI backend. It enforces stack-specific constraints so Claude Code outputs a ready-to-paste CLAUDE.md file for this stack.

The template explains how to structure the project, authentication, data validation, and deployment considerations tailored to Angular Material + FastAPI.

When to Use This CLAUDE.md Template

• When you need a complete CLAUDE.md blueprint that covers both frontend and backend for an Angular Material + FastAPI stack.
• When you want concrete rules for file structure, authentication, data validation, and deployment tailored to this stack.
• When you require a copyable CLAUDE.md block to paste into Claude Code for rapid scaffolding.

Copyable CLAUDE.md Template

# CLAUDE.md

Project role: You are Claude Code. Output is a copyable CLAUDE.md template for an Angular Material + FastAPI Customer Support App. Avoid extraneous prose. Produce a complete, runnable Claude Code block starting with this header.

Architecture rules:
- Use a modular monorepo style with explicit frontend and backend boundaries
- Frontend uses Angular Material components, feature modules, and strongly typed services
- Backend uses FastAPI with routers, Pydantic models, and SQLAlchemy models
- Separate concerns: API layer, business logic layer, and persistence layer
- No cross-stack implicit coupling; communicate via clearly defined DTOs

File structure rules:
- Frontend: angular-material-app/src/app/{feature modules, shared, core}
- Backend: backend/app/{core, api/v1, models, schemas, services}
- Docker and docker-compose at project root; environment files only for secrets in .env
- Use conventional naming and consistent case across both layers

Authentication rules:
- Backend uses OAuth2 password flow with JWT access tokens
- Passwords stored with strong hashing (bcrypt)
- Add a middleware to enforce token validation on protected endpoints
- Frontend stores tokens securely with httpOnly cookies when feasible; refresh token flow implemented

Database rules:
- PostgreSQL as the primary store
- SQLAlchemy ORM models with Alembic migrations
- Use Pydantic schemas for request/response validation
- Enforce unique constraints where appropriate (email, ticketId)

Validation rules:
- Validate all requests with Pydantic models on input and output schemas on the API layer
- Use strict typing for frontend services
- Validate DTOs during transfer between frontend and backend

Security rules:
- Enable CORS only for allowed origins
- Enforce TLS in production; disable debug endpoints
- Do not expose internal database IDs in API responses unless necessary
- Do not hard-code secrets; use environment variables

Testing rules:
- Backend: pytest with httpx for endpoint tests; test fixtures for sample data
- Frontend: unit tests with Jasmine/Karma or Jest; end-to-end tests with Playwright or Cypress
- Include integration tests that cover API to frontend data flow

Deployment rules:
- Docker multi-stage build; separate images for frontend and backend
- Use docker-compose for local dev; Kubernetes manifests for production if applicable
- CI/CD with automatic tests on merge requests

Things Claude must not do:
- Do not output code that bypasses authentication or stores tokens insecurely
- Do not rely on unsafe eval or dynamic imports in the backend
- Do not propose insecure defaults for secrets or permissions
- Do not omit input validation or fail to describe error handling

Recommended Project Structure

frontend-angular-material-app/
  angular-material-app/
    src/
      app/
        core/
        shared/
        features/
          ticketing/
            components/
            services/
            pages/
  angular.json
  package.json
  tsconfig.json
backend-fastapi/
  backend/app/
    api/
      v1/
        endpoints/
    models/
    schemas/
    services/
    main.py
  alembic/
  requirements.txt
  Dockerfile
  docker-compose.yml
infra/
  nginx/
  certs/

Core Engineering Principles

• Clear boundaries between frontend and backend with explicit API contracts
• Strong typing across both layers to minimize runtime errors
• Defensive programming with input validation and explicit error handling
• Security first: proper authentication, token handling, and secret management
• Test-driven approach: unit, integration, and end-to-end tests

Code Construction Rules

• Frontend components must be modular and reusable; avoid tied UI to business logic
• Backend endpoints must have explicit path operations with clear response models
• Use Pydantic models for request/response validation; map to SQLAlchemy models in the persistence layer
• JWT tokens must be used for authentication; implement token refresh securely
• Environment-specific configs must be isolated; do not hard-code in code

Security and Production Rules

• Enable CORS with a limited allowlist; never wide-open in production
• Store secrets in environment variables; use a secret manager in production
• Use TLS termination; enforce HSTS and secure cookies
• Audit and rotate JWT signing keys regularly
• Scan dependencies for known vulnerabilities; pin dependency versions

Testing Checklist

• Backend: unit tests for models, validators, and services
• Backend: integration tests for API endpoints with httpx
• Frontend: unit tests for components and services
• Frontend: integration tests for UI flows; ensure accessibility
• CI: run tests on PRs; ensure linting and type checks pass
• Deployment: verify container builds and environment variable wiring

Common Mistakes to Avoid

• Relying on global state for authentication; prefer explicit dependency injection patterns
• Skipping input validation or exposing sensitive data in responses
• Overmatching the frontend state to backend models; keep API contracts stable
• Neglecting production readiness while iterating features

FAQ

What is the purpose of this CLAUDE.md Template?

A copyable CLAUDE.md blueprint for a stack that combines Angular Material frontend with a FastAPI backend for a customer support app.

Which stack is covered by this template?

Angular Material on the frontend and FastAPI on the backend for a customer support application.

What should Claude output?

A complete CLAUDE.md file that includes a code block starting with the header # CLAUDE.md and all required sections.

Are there security considerations?

Yes, including authentication, token handling, and production-ready security practices in the template.

How is the project structure organized?

Frontend and backend directories with features, APIs, models, schemas, and configs clearly separated.