CLAUDE.md Template: Angular Material + FastAPI + PostgreSQL Starter

Overview

CLAUDE.md Template for Angular Material + FastAPI + PostgreSQL is a copyable Claude Code starter that yields a production-ready skeleton for a full-stack app with a modern UI, robust API, and reliable data persistence.

Direct answer: This CLAUDE.md Template provides a concrete, paste-ready instruction block and project scaffolding for a front-end built with Angular Material, a back-end API with FastAPI, and PostgreSQL as the data store.

When to Use This CLAUDE.md Template

• Kick off a full-stack project using Angular Material for the UI, FastAPI for services, and PostgreSQL for persistence.
• Generate consistent API contracts, validation, and security rules for Claude Code automation.
• Provide a reproducible directory structure and deployment setup for quick onboarding.

Copyable CLAUDE.md Template

# CLAUDE.md
Project role: You are Claude Code, an expert assistant for building a production-grade Angular Material frontend with a FastAPI backend and PostgreSQL database. You produce precise, executable steps and code scaffolds for this stack.

Architecture rules:
- Separate frontend and backend in a monorepo: frontend/ and backend/ with a shared config layer if needed.
- Frontend: Angular Material with standard Material components; API calls to /api/v1/ endpoints.
- Backend: FastAPI app with routers mounted at /api/v1; SQLAlchemy ORM; PostgreSQL database; Alembic migrations for schema changes.
- Config via environment variables and pydantic settings; secret management in deployment.
- Use Docker for development and production; provide docker-compose.yml for dev with frontend, backend, and PostgreSQL.
- Use migrations for DB schema; do not mutate production data outside migrations.

File structure rules:
frontend/
  src/
    app/
      modules/
      components/
      services/
      views/
  angular.json
  package.json
  tsconfig.json
backend/
  app/
    main.py
    api/
      v1/
        endpoints/
        models/
        schemas/
    core/
    db/
  alembic/
  requirements.txt
  Dockerfile

Authentication rules:
- Implement JWT Bearer tokens in FastAPI using OAuth2PasswordBearer or HTTPBearer; protect endpoints under /api/v1/ with dependency injection.
- Use short-lived access tokens; optional refresh tokens; do not expose secrets in logs.
- Frontend stores tokens securely (e.g., HttpOnly cookies or in-memory with refresh).
- Do not bypass authentication for protected routes.

Database rules:
- PostgreSQL database named angular_fastapi_pg; user angular_user; host from environment.
- Use SQLAlchemy ORM models; Pydantic schemas for request/response validation.
- Alembic migrations for schema changes; migration scripts should be versioned.

Validation rules:
- Use Pydantic models with strict types; email, URLs validated; strings trimmed; length constraints applied.
- Validate input on both client and server sides; return clear error messages.

Security rules:
- Enable CORS for allowed origins; do not enable wide-open CORS in production.
- Enforce HTTPS in production; do not log secrets or credentials.
- Do not disable CSRF protection on API endpoints; rely on tokens for API calls.

Testing rules:
- Backend: pytest with httpx for API tests; unit and integration tests for models and endpoints.
- Frontend: Angular tests with Jasmine/Karma; basic component tests; optional Cypress for end-to-end.
- Include test data seeds in tests via fixtures.

Deployment rules:
- Docker Compose for dev; multi-stage Dockerfiles for production images.
- Use environment variables for secrets; run Alembic migrations at startup in production.
- Ensure migrations are deterministic and idempotent.

Things Claude must not do:
- Do not write to production DB without migrations; never mutate production data directly.
- Do not bypass authentication or expose API keys; do not assume default credentials.
- Do not rely on local file system for user uploads; prefer object storage or database storage as appropriate.

Recommended Project Structure

monorepo/
  frontend/
    src/
      app/
        modules/
        components/
        services/
        views/
    angular.json
    package.json
    tsconfig.json
  backend/
    app/
      main.py
      api/
        v1/
          endpoints/
          models/
          schemas/
      core/
      db/
    alembic/
    requirements.txt
    Dockerfile
  docker-compose.yml

Core Engineering Principles

• Single source of truth: architecture rules and code structure must be explicit and enforceable by Claude Code.
• Idempotent deployments: migrations and startup scripts should be safe to run repeatedly.
• Clear separation of concerns between frontend and backend.
• Strong typing and validation on both client and server sides.
• Security-first by default: authentication, authorization, and secrets handling are mandatory.

Code Construction Rules

• Frontend: use Angular Material components for UI; implement a shared design system module; strictly type all APIs with HTTPClient and interfaces.
• Backend: use FastAPI routers under /api/v1; SQLAlchemy models; Pydantic schemas; proper error handling and response models.
• Database: PostgreSQL with migrations; avoid ad-hoc schema changes; seed data via Alembic if needed.
• Environment config: manage with pydantic settings; do not inline secrets in code.
• API contracts: stable endpoints; versioned routes; use OpenAPI documentation generation.

Security and Production Rules

• JWT-based authentication for all protected endpoints; implement token refresh strategy if used.
• Enable CORS with explicit origins; restrict methods and headers.
• Use TLS in production; avoid HTTP in production; do not log secrets or credentials.
• Do not bypass authentication; never expose API keys in client bundles.

Testing Checklist

• Backend: unit tests for models and validators; integration tests for API endpoints using httpx.
• Frontend: unit tests for components and services; ensure API mocks are used.
• Automation: run tests as part of CI; ensure migrations pass in a test environment.

Common Mistakes to Avoid

• Overcomplicating the frontend with non-essential Angular modules; keep to core Material components.
• Relying on client-side validation alone; always enforce server-side validation.
• Skipping migrations; always use Alembic for schema changes.

FAQ

What stack does this CLAUDE.md Template cover?

Angular Material frontend, FastAPI backend, PostgreSQL database.

Is this starter production-ready?

Yes with proper configuration, secrets management, and deployment setup.

How do I customize API endpoints?

Modify backend/app/api/v1/endpoints, update routers, models, and Pydantic schemas.

How do I run the project locally?

Use docker-compose to start frontend, backend, and database; access frontend at localhost:4200 and backend at localhost:8000.

What testing approach is recommended?

Backend: pytest; Frontend: Jasmine/Karma; optionally Cypress for E2E.