CLAUDE.md Template: Angular Material + FastAPI Ticketing System

Overview

A CLAUDE.md template for Angular Material + FastAPI Ticketing System describes how to use Claude Code to scaffold a full-stack ticketing app with a polished Angular Material UI and a FastAPI backend. It covers the frontend in Angular (TypeScript) and the backend in Python, with a PostgreSQL database, JWT-based auth, and clean REST endpoints.

Direct answer: This CLAUDE.md Template provides a precise, stack-specific instruction block that Claude Code can execute to generate a working ticketing system skeleton.

When to Use This CLAUDE.md Template

• When you need a ready-to-run Angular Material + FastAPI ticketing app skeleton in a single repo.
• When you want a reproducible, testable structure with clearly defined API contracts and UI components.
• When you require a versioned database schema with Alembic migrations and Pydantic models for validation.
• When you need Claude Code to generate files in a deterministic layout that supports easy deployment.

Copyable CLAUDE.md Template

# CLAUDE.md

Project role: You are Claude Code, a software engineer and system architect responsible for delivering a complete Angular Material + FastAPI ticketing system in a single monorepo.

Architecture rules:
- Monorepo with frontend/ (Angular) and backend/ (FastAPI).
- Backend uses FastAPI, Pydantic, SQLAlchemy, PostgreSQL; frontend uses Angular with Angular Material.
- API boundaries: REST endpoints with explicit request/response schemas; authentication via JWT/OAuth2; CSRF protection for SPA.
- Provide migrations via Alembic; use Docker Compose for local dev; containerize both services.
- Use a shared environment configuration via environment variables.

File structure rules:
- frontend/
  - angular-app/
    - src/
      - app/
        - components/
        - pages/
        - services/
      - index.html
      - main.ts
- backend/
  - fastapi-app/
    - app/
      - api/
        - routes/
        - dependencies/
      - core/
      - models/
      - schemas/
      - main.py
- infra/
  - docker-compose.yml

Authentication rules:
- JWT-based authentication with OAuth2 password flow; access token expiry short; refresh token rotation.
- Passwords stored with bcrypt; secure cookie-based session for frontend if needed.
- Public endpoints: health check and API docs with proper rate limits.

Database rules:
- PostgreSQL database; SQLAlchemy ORM; Alembic migrations; proper indices on tickets, users, and statuses.
- Data validation at API level via Pydantic models; use database transactions with proper rollback.

Validation rules:
- All inputs validated by Pydantic schemas; strict typing for requests and responses.
- None of the endpoints accept untyped payloads; error responses follow a consistent schema.

Security rules:
- Use HTTPS in all environments; do not serve secrets in source code; use environment-based config.
- Limit CORS to known origins; enable CSRF protection for SPA; rate-limiting for sensitive endpoints.
- Never log plaintext passwords or tokens; rotate JWT signing keys.

Testing rules:
- Backend: pytest with httpx for API tests; unit tests for services and models; integration tests for API contracts.
- Frontend: Angular tests with Jasmine/Karma; end-to-end tests with Cypress if possible.
- Run tests in CI on pull requests; ensure 100% type coverage where feasible.

Deployment rules:
- Docker Compose for local; Dockerfile for frontend and backend; Kubernetes manifests for production if needed.
- Environment-specific config via .env files; secret management via vault or cloud secret store.
- Use migrations on deploy; perform health checks post-deploy.

Things Claude must not do:
- Do not bypass authentication; do not ship secrets; do not rely on client-side validation for security.
- Do not generate code that uses deprecated FastAPI dependencies; avoid insecure default configurations.
- Do not create global singletons that hold sensitive data.

Recommended Project Structure

frontend/
  angular-app/
    src/
      app/
        components/
        pages/
        services/
    angular.json
    package.json
    tsconfig.json
backend/
  fastapi-app/
    app/
      api/
        routes/
        dependencies/
      core/
      models/
      schemas/
      main.py
    alembic/
    requirements.txt
    Dockerfile
    docker-compose.yml
infra/
  docker-compose.yml

Core Engineering Principles

• Strong typing and explicit contracts across frontend and backend (Angular + TypeScript, Pydantic models).
• Clear separation of concerns between UI, API, and data layer.
• Idempotent operations and deterministic file generation in Claude Code templates.
• Reproducible builds and deployments with containerization and migrations.
• Observability through structured logging and metrics; testable code with unit and integration tests.

Code Construction Rules

• Frontend: Use Angular Material components for tickets, forms, and lists; maintain a shared UI component library.
• Backend: Use FastAPI with Pydantic models; repository pattern; SQLAlchemy ORM; Alembic migrations.
• API design: RESTful endpoints with clear request/response schemas; proper error handling and status codes.
• Validation: Enforce strict input validation with Pydantic; never trust client payloads.
• Security: JWT tokens, short expiry, refresh rotation; CSRF protection; HTTPS; secret management via environment variables.
• Performance: Use async endpoints where appropriate; database connection pooling; limit heavy operations.

Security and Production Rules

• Secret management: Use environment variables or a secret store; never commit secrets.
• Transport: Enforce HTTPS in all environments; configure TLS certificates via CI/CD.
• Authentication: Use OAuth2 JWT flows; validate tokens on protected routes.
• Data protection: Encrypt sensitive fields at rest if needed; audit logging for critical actions.
• Deployment: Use migrations; health checks; canary deployments if possible.

Testing Checklist

• Backend: unit tests for services/models; integration tests for routes; contract tests for API schemas.
• Frontend: unit tests for components; integration tests for services; e2e tests for ticket flows.
• CI: run type checks, tests, and linting; verify Docker builds; run migrations in test env.

Common Mistakes to Avoid

• Treating frontend and backend as a single layer; forget to define API contracts clearly.
• Skipping migrations or misaligning DB schema with models.
• Hardcoding secrets or tokens in code; overlooking CORS and CSRF protections for SPA.
• Overcomplicating the project structure; failing to keep separation of concerns.

FAQ

• What is the purpose of this CLAUDE.md Template?
  It provides stack-specific Claude Code instructions to scaffold an Angular Material + FastAPI ticketing system.
• Which files should Claude generate first?
  Frontend: setup Angular module, components, and UI; Backend: create FastAPI app, routers, models, schemas, and DB config.
• How do I run locally?
  Use docker-compose to start frontend and backend; access UI and API at configured ports.
• What about authentication?
  JWT-based authentication with OAuth2 password flow; refresh tokens rotated; secure cookies for frontend sessions.
• What should Claude avoid?
  Avoid leaking secrets, bypassing auth, or generating deprecated patterns; avoid unsafe shortcuts.