CLAUDE.md Template: Angular Material + FastAPI PDF Report Generator

Overview

The CLAUDE.md template is a copyable Claude Code blueprint for a production-ready Angular Material + FastAPI PDF Report Generator. This page targets the Angular Material + FastAPI PDF Report Generator stack.

Direct answer: This CLAUDE.md template provides a complete CLAUDE.md block that you can paste into your project to scaffold roles, architecture rules, and deployment guidelines for this stack.

When to Use This CLAUDE.md Template

• You are building a PDF report system with an Angular Material frontend and a FastAPI backend.
• You need a ready-to-paste Claude Code block to capture project rules and deployment details.
• You want consistent engineering principles across frontend and backend bound by a common interface for PDF generation.

Copyable CLAUDE.md Template

# CLAUDE.md

Project role
- You are implementing a PDF report generator with an Angular Material UI and a FastAPI backend. Claude should guide architecture, validations, and deployment.

Architecture rules
- The frontend is an Angular Material SPA consuming a REST API from the FastAPI backend.
- The backend exposes a /reports/pdf endpoint that returns a generated PDF with appropriate headers.
- Use WeasyPrint to render HTML templates into PDFs on the server side.
- Ensure clear separation between frontend and backend concerns with a shared interface layer for data contracts.

File structure rules
- Keep frontend and backend in separate top-level folders: /frontend and /backend.
- Include a /shared folder for shared types and utilities used by both sides.
- Include /docs for design docs and CLAUDE.md templates.

Authentication rules
- Use OAuth2 with JWT access tokens for API authentication.
- Token must be provided in the Authorization: Bearer  header.
- Backend must validate tokens on all PDF-generation endpoints.

Database rules
- Use PostgreSQL with SQLModel/SQLAlchemy ORM in FastAPI.
- Migrations must be managed via Alembic and run during deployment.
- Secrets must be retrieved from a secure store, not hard-coded.

Validation rules
- Use Pydantic models for request validation and response schemas.
- All inputs must be strictly validated (types, required fields, value ranges).

Security rules
- Enforce HTTPS in all environments; disable insecure HTTP.
- Implement CORS with a minimal allowlist for frontend origins.
- Do not log sensitive payloads; mask PII in logs.

Testing rules
- Backend: unit tests for models, services, and API endpoints with pytest.
- Backend: integration tests mocking the PDF generator.
- Frontend: unit tests with Jest + Angular Testing Library.
- E2E: Cypress tests for the PDF generation flow.

Deployment rules
- Dockerize frontend and backend; compose with docker-compose.yml.
- Use environment variables for secrets and config; do not bake secrets into images.
- Run database migrations on startup in production.
- Enable production optimizations (minification, tree-shaking) for frontend.

Things Claude must not do
- Do not introduce credentials, secrets, or hard-coded tokens.
- Do not bypass authentication checks or disable security rules.
- Do not generate emails or push notifications without consent.
- Do not assume external services without explicit configuration.

Recommended Project Structure

.
├── frontend/
│   ├── src/
│   │   ├── app/
│   │   │   └── components/
│   │   ├── main.ts
│   │   └── styles.css
│   ├── angular.json
│   └── package.json
├── backend/
│   ├── app/
│   │   ├── main.py
│   │   ├── api/
│   │   │   └── pdf.py
│   │   ├── models/
│   │   └── services/
│   ├── requirements.txt
│   └── alembic/
├── shared/
│   └── schemas/
├── docs/
├── docker-compose.yml
├── Dockerfile-frontend
├── Dockerfile-backend
└── README.md

Core Engineering Principles

• Explicit contracts between frontend and backend via typed data models.
• Single responsibility: frontend handles UI, backend handles PDF generation and data persistence.
• Compiler-friendly: TypeScript types on the frontend, Pydantic models on the backend.
• Idempotent API design for report generation endpoints.
• Observable behavior with structured logging and tracing.

Code Construction Rules

• Frontend code must be in TypeScript with strict type checking and Angular best practices.
• Backend must be Python 3.11+ with FastAPI and async endpoints; PDF generation must be isolated in a service.
• Data contracts must be defined as shared types in /shared and imported by frontend and backend where appropriate.
• Do not hard-code URLs; use environment-based configuration.
• Do not bypass authentication for PDF endpoints.

Security and Production Rules

• Always run with HTTPS in production; terminate TLS at reverse proxy or load balancer.
• Keep secrets in a secure secret store; inject at container startup via environment variables.
• Enable CORS with a narrow allowed origins list including the SPA host.
• Audit logs for access to PDF generation endpoints; mask sensitive content in logs.

Testing Checklist

• Backend unit tests for models and services.
• Backend integration tests for API endpoints and PDF renderer.
• Frontend unit tests for components and services.
• End-to-end tests validating the PDF generation flow from the UI.
• CI pipelines run tests on push and pull requests.

Common Mistakes to Avoid

• Over-bloating the frontend with nonessential dependencies; keep Material usage lean.
• Skipping migrations or directly editing the production database.
• Not validating request payloads on the backend; trust but verify.
• Ignoring production security requirements in local development.

FAQ

• What is this CLAUDE.md Template for? It provides a copyable Claude Code blueprint for an Angular Material + FastAPI PDF generator.
• Which stack does this template cover? Angular Material frontend, FastAPI backend, and PDF generation (WeasyPrint).
• How do I use the template? Copy the CLAUDE.md block into your CLAUDE.md file and adapt paths, endpoints, and configs.
• What about security? Use JWTs, HTTPS, CORS, and secure secret management as outlined above.
• How do I deploy? Use Docker Compose to run frontend and backend with migrations and production settings.