CLAUDE.md Template: Angular Material + FastAPI CRUD App Starter

Overview

The CLAUDE.md template for Angular Material + FastAPI CRUD App is a copyable Claude Code starter that helps you scaffold a secure, testable, full-stack application. It covers an Angular Material SPA frontend and a FastAPI backend with PostgreSQL, JWT authentication, and a clean project structure.

Direct answer: Use this CLAUDE.md Template to reproduce a production-ready full-stack Angular Material + FastAPI CRUD app with a Claude Code block you can paste into CLAUDE.md.

When to Use This CLAUDE.md Template

• You need a ready-to-use Claude Code starter for an Angular Material + FastAPI CRUD app.
• You want explicit rules for architecture, file structure, and security to prevent drift.
• You require a repeatable blueprint for containerized frontend and backend deployment.

Copyable CLAUDE.md Template

# CLAUDE.md
Project role: You are a senior frontend-backend architect tasked with generating a complete, production-ready Angular Material + FastAPI CRUD application scaffold. Provide a clean, secure, and testable Claude Code starter that a developer can paste directly into CLAUDE.md to reproduce the stack.

Architecture rules:
- Frontend: Angular 15+ with Angular Material components
- Backend: FastAPI with SQLAlchemy (PostgreSQL) and Alembic migrations
- Communication: REST over HTTPS; use JWT for authentication
- Database: PostgreSQL; separate read/write databases if scaling is needed; migrations via Alembic
- Deployment: Dockerized frontend and backend behind a reverse proxy
- Observability: add basic logging and structured error responses
- Do not couple backend models to frontend UI details

File structure rules:
- frontend/
  - src/
    - app/
      - core/
      - features/
      - shared/
      - components/
      - services/
  - angular.json
  - package.json
  - tsconfig.json
- backend/
  - app/
    - api/
    - models/
    - routes/
    - core/
    - schemas/
  - alembic/
  - requirements.txt
  - Dockerfile.backend
- shared/
  - common/
  - dto/
  - constants/

Authentication rules:
- JWT Bearer tokens; use OAuth2PasswordBearer for token endpoints
- Passwords hashed with Argon2 or bcrypt; never store plain passwords
- Use refresh tokens with short lifetimes and rotation
- Do not send tokens in URL query parameters

Database rules:
- PostgreSQL as primary database
- SQLAlchemy ORM models with proper relationships
- Alembic migrations; seed data in a separate migration if needed
- Use UUID as primary keys when possible

Validation rules:
- Pydantic models for request/response validation
- Validate all inputs; return 422 on invalid data
- Ensure numeric ranges for CRUD operations (e.g., pagination limits)

Security rules:
- Use HTTPS in all environments
- Enable CORS for the SPA domain only
- Do not expose raw database connection strings; use environment variables
- Do not enable insecure endpoints in production

Testing rules:
- Backend: pytest + httpx.AsyncClient for endpoints
- Frontend: Cypress or Playwright for UI flows
- Include unit tests for CRUD operations and authentication
- Include integration tests for API models and schemas

Deployment rules:
- Docker Compose with frontend and backend services
- Backend runs with uvicorn; frontend served by Nginx or static hosting
- Use environment-specific .env files and secret management

Things Claude must not do:
- Do not generate code that uses localStorage for tokens
- Do not hard-code secrets in CLAUDE.md
- Do not use deprecated libraries or insecure crypto
- Do not bypass authentication or authorization checks

Recommended Project Structure

frontend/
  src/
    app/
      core/
      features/
      shared/
      components/
  angular.json
  package.json
  tsconfig.json

backend/
  app/
    api/
    models/
    routes/
    core/
    schemas/
  alembic/
  requirements.txt
  Dockerfile.backend

docker-compose.yml

Core Engineering Principles

• Clear separation of concerns between frontend and backend.
• Type-safe boundaries with explicit schemas for requests and responses.
• Idempotent, well-documented API endpoints for CRUD resources.
• Strong validation, error handling, logging, and observability basics.
• Accessible UI with Angular Material components and responsive design.

Code Construction Rules

• Frontend uses Angular Material components with proper theming and accessibility attributes.
• Backend endpoints follow REST conventions for CRUD on the resource (GET, POST, PUT, DELETE).
• Models use SQLAlchemy ORM; Pydantic models validate request payloads.
• Environment-driven configuration; no secrets in code.
• Respect the project structure rules; avoid coupling between frontend and backend code paths.
• Do not import/disclose database credentials in source files.

Security and Production Rules

• Enforce HTTPS in all environments; use reverse proxy SSL termination.
• CORS allowed origins limited to the SPA domain.
• JWT tokens must be validated and rotated; refresh tokens with short lifetimes.
• Audit logs for sensitive actions; avoid leaking PII in error messages.

Testing Checklist

• Backend: unit tests for models, schemas, and CRUD endpoints.
• Backend: integration tests with test database (PostgreSQL) and migrations.
• Frontend: unit tests for components and services.
• Frontend: end-to-end tests for login, CRUD flows, and navigation.
• CI: run tests, linting, and type checks on push.

Common Mistakes to Avoid

• Placing business logic in UI components instead of services.
• Ignoring input validation and trusting client-side validation only.
• Reusing auth tokens insecurely or exposing tokens in logs.
• Skipping migrations; evolving the schema only by manual changes.

FAQ