CLAUDE.md Template: Angular Material + FastAPI Workflow App

Overview

A CLAUDE.md template tailored for a stack with Angular Material on the frontend and FastAPI on the backend. This page serves as a copyable CLAUDE.md template for Claude Code that defines roles, architecture, file structure, authentication, database, validation, security, testing, deployment, and strict do-not rules for this stack.

Use this CLAUDE.md template to drive consistent project scaffolding and automated code generation for an Angular Material + FastAPI workflow app using Claude Code.

When to Use This CLAUDE.md Template

• Starting a new Angular Material + FastAPI workflow project with Claude Code
• Onboarding teams to a shared frontend-backend contract
• Enforcing security, testing, and deployment rules from day 1

Copyable CLAUDE.md Template

# CLAUDE.md

Project role: Full-stack engineer building an Angular Material frontend and FastAPI backend for a workflow app.
Architecture rules:
- Monorepo with apps/angular-app and apps/fastapi-backend; shared models in libs.
- Backend: FastAPI with APIRouter, Pydantic models, SQLAlchemy ORM; PostgreSQL as the database.
- Frontend: Angular with Angular Material; HttpClient services; RxJS for state handling.
- API contracts are strict; use common DTOs for requests and responses.
- Authentication relies on JWT tokens passed in Authorization header; refresh tokens rotated securely.
- Config via environment variables for both frontend and backend; no hard-coded secrets.
- All endpoints validated; consistent error handling and status codes.
- Use CI to run tests and linting; code must be production-ready before deployment.

File structure rules:
- apps/angular-app/src/app/ contains components/, pages/, services/, shared/
- apps/fastapi-backend/app/ contains main.py, api/v1/endpoints/, models/, core/, schemas/
- libs/shared/ contains shared data models and DTOs
- infrastructure/ contains deployment assets (Dockerfiles, manifests)

Authentication rules:
- Use OAuth2 / JWT with access and refresh tokens; protected endpoints require current_user
- Tokens stored securely in Authorization header or HTTP-only cookies
- Ensure token expiry and rotation policies are enforced

Database rules:
- PostgreSQL with SQLAlchemy ORM; Alembic for migrations
- Use typed Pydantic models for requests/responses; avoid raw SQL in handlers

Validation rules:
- Pydantic in backend; TypeScript interfaces in frontend; strict type checks
- Enforce field lengths, required properties, and allowed enums

Security rules:
- TLS everywhere; TLS termination at reverse proxy
- CSRF protections if cookies are used; otherwise rely on Authorization header
- CSP, HSTS, and strict CORS settings to trusted origins only
- Secrets managed via environment variables; never committed

Testing rules:
- Backend: pytest with test database; tests for endpoints and models
- Frontend: Jest + Angular Testing Library; unit and integration tests for components/services
- CI should run unit, integration, and basic end-to-end smoke tests

Deployment rules:
- Docker multi-stage builds; docker-compose for local dev; Kubernetes manifests for prod
- Build in production mode for frontend; serve with a static server or Nginx
- Secrets provided via environment variables or a secret management tool

Things Claude must not do:
- Do not bypass authentication nor expose tokens in logs
- Do not bypass input validation or permit unsafe data
- Do not generate code with hard-coded secrets or deprecated libraries
- Do not expose internal schemas or production data

Recommended Project Structure

apps/
  angular-app/
    src/
      app/
        components/
        pages/
        services/
        shared/
    angular.json
    package.json
  fastapi-backend/
    app/
      main.py
      api/
        v1/
          endpoints/
      models/
      core/
      schemas/
      config/
    requirements.txt
libs/
  shared/
Dockerfile
docker-compose.yml

Core Engineering Principles

• Explicit API contracts between Angular and FastAPI using shared DTOs
• Security by default: authentication, authorization, and auditing
• Separation of concerns: frontend, backend, and shared models
• Test-driven development with unit, integration, and e2e tests
• Observability: structured logging and metrics for both frontend and backend

Code Construction Rules

• Frontend uses Angular Material with a clean component library
• Backend uses FastAPI with APIRouter and Pydantic models
• Shared models in a common library to ensure contract parity
• Async endpoints for IO-bound tasks
• Do not bypass authentication or leak secrets in code or logs

Security and Production Rules

• JWT-based authentication; protect endpoints with dependency checks
• HTTPS everywhere; TLS termination at reverse proxy
• CSRF considerations for cookie-based sessions; otherwise rely on Authorization header
• Content Security Policy (CSP), HSTS, strict CORS
• Secrets managed via environment variables or secret stores; avoid hard-coding

Testing Checklist

• Unit tests for Angular components and services
• Unit tests for FastAPI models and endpoints
• Integration tests for API and database interactions
• End-to-end smoke tests in CI

Common Mistakes to Avoid

• Skipping backend validation for API requests
• Not aligning frontend and backend contracts
• Storing secrets in code or uncontrolled environments
• Relying solely on client-side validation for security

FAQ

• What is this CLAUDE.md Template for Angular Material + FastAPI? This CLAUDE.md template provides a blueprint to implement a full-stack workflow app with Angular Material on the frontend and FastAPI on the backend, including security, tests, and deployment guidance.
• Which stack is covered? Angular Material frontend with a FastAPI backend, PostgreSQL database, and Claude Code automation for scaffolding.
• How should the project be structured? A monorepo-like layout with separate angular-app and fastapi-backend apps, plus a shared models library.
• What are the deployment requirements? Docker multi-stage builds, Docker Compose for development, and Kubernetes manifests for production; TLS and secrets management required.
• What security practices are enforced? JWT authentication, proper token handling, CSP, secure CORS, and secret management; avoid exposing sensitive data.