CLAUDE.md Template: Angular Material + FastAPI Report Generator

Overview

This CLAUDE.md template is designed for an Angular Material frontend paired with a FastAPI backend to generate reports. It provides Claude Code instructions, defining architecture, file structure, and operational policies. It targets a stack where the frontend consumes a REST API served by FastAPI, with report rendering on the client, and optional server-side PDF/HTML rendering.

When to Use This CLAUDE.md Template

• When you need a repeatable CLAUDE.md skeleton for a full-stack Angular Material + FastAPI project.
• When the goal is to generate clean, reproducible Claude Code prompts for frontend-backend report generation.
• When you want a copyable template to drop into CLAUDE.md for your repository.
• When you want strict architecture rules and security considerations baked in.

Copyable CLAUDE.md Template

# CLAUDE.md
Project role: You are a collaborative engineer who helps generate deterministic reports from a FastAPI backend and an Angular Material frontend. You must produce clear, well-typed output that can be rendered in a browser or converted to PDF. You are part of a team that uses Claude Code in the context of a frontend-backend stack.

Architecture rules:
- Frontend: Angular Material SPA communicates with the FastAPI backend via REST endpoints over HTTPS. Use OpenAPI specs and strict type contracts.
- Backend: FastAPI with Pydantic models. All endpoints validate input and sanitize output. Use async I/O and dependency injection. 
- Data contracts: Use explicit schemas for request/response. No implicit casts.
- Reporting: Generate reports on demand; support HTML and PDF formats as optional outputs.

File structure rules:
- Place shared types in a common folder accessible to both frontend and backend (e.g., "shared/models").
- Frontend src structure: src/app/... components, services, guards, and environments. Backend: app/..., routers, models, schemas, and services.
- Do not place server-only code in frontend folders.
- Do not duplicate model schemas across frontend and backend; share via a common schema folder.

Authentication rules:
- Use OAuth2 with password grant for API tokens in development; switch to OAuth2 PKCE in production if needed.
- Backend validates tokens; frontend sends Authorization header: Bearer .
- Do not expose user passwords via API responses.

Database rules:
- Use an in-memory or PostgreSQL database for development and production; keep credentials in environment variables.
- FastAPI endpoints must not leak connection strings in responses.
- Use SQLAlchemy with Alembic migrations or equivalent for schema versioning.

Validation rules:
- All requests must be schema-validated by Pydantic models on the backend.
- Frontend forms must enforce client-side validation with Angular reactive forms and material validators.

Security rules:
- Always use HTTPS in dev with self-signed certs; enforce HSTS in production.
- Do not log sensitive data; redact PII in logs.
- Use CSRF protection for state-changing requests in the frontend.
- Validate CORS policies on the backend and keep allowed origins minimal.

Testing rules:
- Backend: unit tests for Pydantic models and endpoints; use pytest with httpx for async requests.
- Frontend: unit tests for components and services; Cypress for end-to-end tests.
- CI: run unit tests on PRs and ensure type checks pass.

Deployment rules:
- Dockerize both frontend and backend; use docker-compose for local development.
- Use separate containers for frontend and backend; ensure health checks are in place.
- Environment variables should be loaded via a .env file or secret manager in CI/CD.

Things Claude must not do:
- Do not bypass authentication checks or leak tokens.
- Do not generate code that uses eval/exec with user input.
- Do not assume a particular cloud provider; avoid provider-specific services unless required.
- Do not produce output that reveals server internal stack traces to clients.

Recommended Project Structure

angular-fastapi-report/
├── frontend/
│   ├── src/
│   │   ├── app/
│   │   │   ├── components/
│   │   │   ├── services/
│   │   │   └── app.module.ts
│   │   └── styles.css
│   ├── angular.json
│   ├── package.json
│   └── tsconfig.json
├── backend/
│   ├── app/
│   │   ├── main.py
│   │   ├── routers/
│   │   ├── models/
│   │   ├── schemas/
│   │   └── services/
│   ├── requirements.txt
│   └── Dockerfile
└── README.md

Core Engineering Principles

• Explicit contracts between frontend and backend via OpenAPI/Pydantic models.
• Type safety across both layers to minimize runtime errors.
• Separation of concerns: clear division between UI, API, and data access.
• Defensive defaults with strong input validation and sanitization.
• Idempotent operations and predictable side effects for reports.

Code Construction Rules

• Follow Angular Material patterns for components and forms; reuse shared UI components where possible.
• Use FastAPI routers for endpoints; group by feature and document with OpenAPI.
• Publish strong, typed request/response models in a shared schema layer.
• Keep environment-specific values in environment variables; avoid hard-coded credentials.
• Ensure all API routes validate and sanitize inputs; guard against SQL/NoSQL injection where applicable.

Security and Production Rules

• Enforce HTTPS in all environments; use HSTS in production.
• Do not expose internal stack traces or debug information to clients.
• Use CSRF protection for frontend state-changing requests to the backend.
• Implement proper CORS policies with restricted origins.

Testing Checklist

• Backend: unit tests for Pydantic models and endpoints; use pytest and httpx.
• Frontend: unit tests for components/services; use Jasmine/Karma or Jest with Angular testing utilities.
• End-to-end: Cypress scripts for report generation workflows.
• CI: ensure type checks, linting, and tests pass on PRs.

Common Mistakes to Avoid

• Rushing to build UI mocks without solid OpenAPI contracts.
• Neglecting input validation on the backend; relying on frontend validation only.
• Hard-coding secrets or credentials in the codebase.
• Ignoring production readiness checks like health probes and logging formats.

FAQ

• What is a CLAUDE.md template? It’s a copyable blueprint for Claude Code to generate structured guidance for a stack-specific project.
• Why Angular Material + FastAPI? This combination provides a modern UI with a fast, type-safe API layer and a straightforward report-generation workflow.
• How do I customize? Edit the CLAUDE.md block and project structure to match your endpoints, models, and UI components.
• Where do I put this? In your repository root under a dedicated CLAUDE.md Templates collection page.
• How to run? Start frontend and backend locally using docker-compose or npm run/start and uvicorn.