CLAUDE.md Template: Angular Material + Starlette API Starter (CLAUDE.md template)

Overview

This CLAUDE.md template is designed for developers building a full-stack project with an Angular Material frontend and a Starlette API backend. It provides a concrete CLAUDE.md template block that instructs Claude Code on how to scaffold, wire, and validate core features (UI components, API routes, authentication, data validation, and deployment) in a cohesive, maintainable way.

When to Use This CLAUDE.md Template

• You are starting a new Angular Material + Starlette project and need a repeatable CLAUDE.md workflow.
• You want a copyable, auditable CLAUDE.md that codifies architecture rules and file structure for this stack.
• You need a starting point that enforces security, validation, and deployment guidelines from day one.

Copyable CLAUDE.md Template

# CLAUDE.md

Project role: Full-stack developer integrating an Angular Material frontend with a Starlette API backend.

Stack overview: Angular 16+ with Angular Material UI; Python 3.11+; Starlette for API; Uvicorn for ASGI server; PostgreSQL for data persistence.

Architecture rules:
- Separate frontend and API into distinct folders with clear boundaries.
- All API routes live under /api with standard REST patterns.
- Use JWT-based authentication for API endpoints; frontend should obtain tokens via a dedicated auth service.
- Frontend state is managed via Angular services; avoid direct DOM manipulation outside components.
- Config is environment-based; do not embed secrets in the codebase.

File structure rules:
- frontend/angular-material-app/
  - src/app/            # Components, services, models
  - src/environments/   # Environment configs
  - angular.json
  - package.json
- backend/starlette-app/
  - app/
    - api/               # Routers and endpoints
    - core/              # Config, security, utilities
    - models/            # Pydantic models
  - main.py                # ASGI app
  - requirements.txt
- shared/                # DTOs and shared validation rules
- docker/                # Docker-related files (compose, Dockerfiles)

Authentication rules:
- Use JWTs with short-lived access tokens and refresh tokens stored securely.
- Protect endpoints with bearer auth; verify scopes/roles per route.
- Do not bypass CSRF checks for API calls from SPA; use same-site cookies or explicit tokens.

Database rules:
- PostgreSQL as the primary database.
- Use SQLAlchemy 2.0 models or Pydantic-based validation with async DB access.
- Do not hardcode credentials; fetch from environment variables.

Validation rules:
- Validate input data via Pydantic models on the backend; validate all inputs on the frontend before API calls.
- Normalize and sanitize all outputs to prevent injection.

Security rules:
- Enforce HTTPS in production; enable CORS for the frontend domain only.
- Never log sensitive data (tokens, passwords).

Testing rules:
- Backend: pytest + httpx for integration tests; mock external services.
- Frontend: Angular testing with Jest and Angular Testing Library.
- CI should run unit, integration, and end-to-end tests where feasible.

Deployment rules:
- Use docker-compose to run frontend and backend together in dev; production uses orchestrator (K8s or similar).
- Secrets must be provided via env vars; do not bake secrets into images.
- Build each service with reproducible CI/CD pipelines.

Things Claude must not do:
- Do not generate credentials, secret keys, or hard-coded tokens.
- Do not bypass authentication or authorize requests without proper checks.
- Do not couple frontend and backend logic beyond intended API contracts.
- Do not introduce unsafe dependencies or direct DOM mutations outside Angular Material components.

Recommended Project Structure

frontend/                  # Angular Material SPA
  angular-material-app/
    src/
      app/
        components/
        services/
        models/
      main.ts
      app.module.ts
    angular.json
    package.json
backend/                   # Starlette API
  starlette-app/
    app/
      api/
        routes/
        endpoints/
      core/
      models/
    main.py
    requirements.txt
docker/
  docker-compose.yml
  Dockerfile.frontend
  Dockerfile.backend

README.md

Core Engineering Principles

• Clear separation of concerns between frontend UI and backend API.
• Type safety across TypeScript (Angular) and Python (Starlette/Pydantic).
• Declarative UI with reusable components and consistent design tokens (Angular Material).
• Stateless API design with consistent error handling and responses.
• Config-driven behavior with environment-based settings.
• Observability: structured logs, error reporting, and health checks.

Code Construction Rules

• Frontend components must use Angular Material conventions and the Angular style guide.
• API routes must follow REST conventions under /api with clear nouns.
• Use Pydantic models for input validation on the backend; type hints are mandatory.
• JWT-based authentication with scope checks on each protected endpoint.
• Environment-based configuration and secret management; never commit credentials.
• Do not mix server-side rendering in the Starlette API; keep SSR out of API routes.

Security and Production Rules

• Enable HTTPS in all production environments; enforce TLS 1.2+.
• Restrict CORS to the Angular app origin and approved domains only.
• Validate and rate-limit API calls; implement token revocation strategy.
• Store secrets in environment variables or secret managers; avoid code-based secrets.
• Regularly rotate JWT signing keys and monitor for unusual auth activity.

Testing Checklist

• Backend: unit tests for models and validators; integration tests for /api endpoints.
• Frontend: unit tests for components; end-to-end tests that cover login flow and data display.
• CI: run linting, tests, and type checks in PRs; ensure Docker builds succeed.

Common Mistakes to Avoid

• Not isolating frontend and API concerns leading to tight coupling.
• Hardcoding secrets or API keys in the codebase.
• Under-specifying input validation or over-trusting client data.
• Ignoring CORS and authentication edge cases in development vs production.

FAQ