Angular Material + FastAPI Project Management CLAUDE.md Template

Overview

The CLAUDE.md template is designed for a full-stack Angular Material frontend paired with a FastAPI backend to support project management features. It yields a copyable CLAUDE.md template block and stack-specific guidance so developers can quickly generate scaffold code, wire frontend with API, and enforce consistent architecture across teams. Direct answer: this page provides a CLAUDE.md template you can paste into Claude Code to generate a ready-to-run Angular Material + FastAPI project scaffold.

When to Use This CLAUDE.md Template

• Starting a new project with a modern Angular Material UI and FastAPI backend.
• Establishing a repeatable CLAUDE.md block for automated code generation.
• Documenting stack-specific rules for frontend-backend integration and deployment.

Copyable CLAUDE.md Template

# CLAUDE.md

Project role: You are Claude Code tasked with generating a complete Angular Material frontend and FastAPI backend project for a project management tool. The output must be a clean, opinionated starter with unit tests, containerized deployment, and clear engineering rules.

Architecture rules:
- Monorepo layout with frontend and backend under a single repository
- Frontend uses Angular + Angular Material, TypeScript, and RxJS
- Backend uses FastAPI with Pydantic models and SQLAlchemy for PostgreSQL
- Backend API versioning: v1
- Use JWT-based authentication with OAuth2PasswordBearer on the backend
- Database migrations via Alembic
- Dockerized deployment with docker-compose for local dev
- End-to-end tests optional but recommended

File structure rules:
- frontend/ contains Angular app with src/app, assets, environments
- backend/ contains app/, core/, db/, api/v1, tests/ directories
- docker-compose.yml ties frontend and backend together

Authentication rules:
- JWT access token with 15-minute expiry; refresh token rotation
- Use OAuth2 password flow on the API and pass tokens via Authorization header
- Do not rely on session cookies for API authentication

Database rules:
- PostgreSQL database managed by SQLAlchemy models
- Alembic migrations tracked in migrations/ folder
- Use proper ORM relationships and index optimization

Validation rules:
- Pydantic models on the API layer; strict request/response schemas
- Client-side TypeScript interfaces mirror API models

Security rules:
- Do not hardcode secrets; read from environment variables
- Enforce HTTPS in all environments
- Validate input to prevent injection and over-posting
- Do not expose internal schemas via unprotected endpoints

Testing rules:
- Backend tests with pytest covering models, services, and API endpoints
- Frontend tests with Jasmine/Karma for components and services
- Run tests in CI and deliver a lightweight local test run for developers

Deployment rules:
- Build images with docker-compose up --build in CI and locally
- Use environment-specific .env files; no hardcoded credentials
- Health checks and graceful shutdown for FastAPI and Angular

Things Claude must not do:
- Do not generate insecure authentication flows
- Do not omit input validation or produce unchecked user input
- Do not create permissive CORS or insecure defaults

Recommended Project Structure

frontend/
  src/
    app/
      components/
      services/
      models/
      pages/
      app.module.ts
      app-routing.module.ts
  angular.json
  package.json
  tsconfig.json

backend/
  app/
    main.py
    api/
      v1/
        endpoints/
        models/
        schemas/
    core/
      config.py
    db/
      base.py
  alembic/
  requirements.txt
  Dockerfile
  docker-compose.yml

Core Engineering Principles

• Clear boundary between frontend and backend with explicit interfaces
• Type-safe data contracts shared or mirrored across layers
• Defensive programming and input validation by default
• Incremental changes with test coverage at unit and integration levels
• Secure defaults and minimal surface area for security

Code Construction Rules

• Frontend uses Angular Material components for UI patterns and accessibility
• Backend exposes REST endpoints via FastAPI; use APIRouter per resource
• Models: SQLAlchemy for persistence; Pydantic for validation/serialization
• Authentication via OAuth2 with JWT tokens; Bearer token in Authorization header
• Consistent DTOs; avoid leaking internal schemas through public APIs
• Do not rely on insecure eval, dynamic code generation, or inline secrets

Security and Production Rules

• Environment-based configuration; use secrets from environment, not code
• HTTPS required in production; use a reverse proxy or cloud load balancer
• CORS restricted to frontend URL(s)
• Short-lived access tokens with secure refresh strategy
• Audit logs and error handling without exposing stack traces

Testing Checklist

• Unit tests for frontend components/services
• Unit tests for backend models and services
• Integration tests for API endpoints and data access
• CI validation to run tests and lint checks

Common Mistakes to Avoid

• Skipping migrations or mixing schema versions
• Over-permissive CORS or insecure token storage in the client
• Unsafe user input handling or missing input validation
• Disconnect between frontend interfaces and backend models

FAQ