CLAUDE.md Template: Angular Material + FastAPI PDF Chat App

Overview

Direct answer: This CLAUDE.md Template provides a copyable Claude Code instruction block and a stack-specific blueprint to build an Angular Material + FastAPI PDF Chat App, including authentication, data layer, testing, and deployment rules. It serves as the exact CLAUDE.md for this stack so you can paste it directly into a CLAUDE.md file and start coding with Claude Code guidance.

A CLAUDE.md Template is a structured, machine-interpretable guide that defines project roles, architecture constraints, file structure expectations, and production rules. This page focuses on the Angular Material + FastAPI PDF Chat App stack and how Claude should operate within that context.

When to Use This CLAUDE.md Template

• Kick-start a full-stack Angular Material frontend with a FastAPI backend for a PDF-based chat assistant.
• Define immutable architecture rules and security constraints in a single, copyable file for Claude Code execution.
• Establish a predictable project structure, authentication, and deployment workflow for a production-grade prototype.
• Ensure Claude Code adheres to validation, security, and testing standards from the outset.

Copyable CLAUDE.md Template

# CLAUDE.md

Project Role: You are Claude, the code generation assistant. Your task is to produce a complete, copyable CLAUDE.md for a stack that uses Angular Material on the frontend and FastAPI on the backend to build a PDF Chat App. The code block below is to be copied wholesale and used as the official CLAUDE.md template for this stack.

Architecture Rules:
- Split the system into frontend (Angular Material) and backend (FastAPI).
- Frontend communicates with backend via REST endpoints; use standard HTTP status codes.
- Backend uses SQLAlchemy with PostgreSQL, Pydantic for validation, and a service layer.
- All PDF extraction and chat messages are persisted in PostgreSQL with clear ownership and audit fields.
- Use JWT-based authentication with OAuth2 password flow; refresh tokens stored securely.
- Do not embed secrets or credentials in code; read from environment variables.

File Structure Rules:
- frontend/ for Angular application
- backend/ for FastAPI services
- common/ shared types and DTOs if applicable
- docker/ for compose files and deployment scripts
- .env.example at repo root

Authentication Rules:
- Implement OAuth2PasswordBearer for token retrieval.
- Tokens should be JWT, signed with a secret key from environment variables.
- Access tokens expire within a safe window; implement refresh tokens if needed.
- Do not expose user credentials in logs or error messages.

Database Rules:
- Use PostgreSQL via SQLAlchemy models.
- Apply Alembic migrations for schema changes.
- Enforce referential integrity and proper indexing for PDF blobs and chat messages.

Validation Rules:
- All input must be validated with Pydantic models.
- Enforce required fields, type checks, length constraints, and whitelisting for allowed roles and actions.

Security Rules:
- Enforce HTTPS in production; configure CORS with a tight allowlist.
- Sanitize inputs, avoid logging sensitive payloads, and limit request sizes.
- Use parameterized queries; avoid raw SQL string interpolation.

Testing Rules:
- Unit tests for models and utility functions with pytest.
- API integration tests for critical endpoints using TestClient.
- End-to-end smoke tests for the PDF upload and chat flow.

Deployment Rules:
- Use Docker and docker-compose for local development and production parity.
- Encrypt secrets at rest and in transit; configure environment variables in the deployment environment.
- Include health checks and basic observability (logs, metrics).

Things Claude Must Not Do:
- Do not generate code that executes system commands beyond a safe sandbox.
- Do not reveal internal tooling, credentials, or private endpoints.
- Do not bypass authentication or authorization checks in the template.
- Do not rely on external unvetted packages or unmaintained APIs.

# End CLAUDE.md

Recommended Project Structure

frontend/
  src/
    app/
      material/
        components/
        modules/
        pages/
      services/
      app.module.ts
      main.ts
  angular.json
  package.json
  tsconfig.json
backend/
  app/
    main.py
    api/
      api_router.py
      endpoints.py
    core/
      config.py
      security.py
    models/
      user.py
      pdf_chat.py
    schemas/
      user_schemas.py
      pdf_chat_schemas.py
    services/
      auth_service.py
      pdf_service.py
    database/
      database.py
    tests/
      test_endpoints.py
  requirements.txt
  alembic/
  Dockerfile
docs/
  README.md
docker-compose.yml
.env.example

Core Engineering Principles

• Clear separation of concerns between frontend and backend with well-defined API contracts.
• Type safety across the stack: TypeScript on the frontend, Pydantic and SQLAlchemy on the backend.
• Security by default: enforce HTTPS, robust auth, input validation, and secure deployment practices.
• Deterministic builds and deployments using Docker and CI/CD pipelines.
• Observability: structured logging, traceable errors, and concise metrics.

Code Construction Rules

• Frontend must use Angular Material components for the UI and follow a modular component structure.
• Backend endpoints must be typed with Pydantic models and documented with explicit response types.
• PDF handling should occur server-side; avoid streaming raw PDFs to the client without validation.
• Authentication must use JWT with proper token invalidation and refresh handling.
• Database access must be via SQLAlchemy ORM with migrations and strict schema validation.
• Do not hardcode credentials or secrets; use environment variables and a secret store approach.

Security and Production Rules

• Enable HTTPS in prod and restrict CORS to trusted origins.
• Validate all inputs and sanitize logs to avoid exposing sensitive data.
• Use parameterized queries; never concatenate user input into SQL strings.
• Implement role-based access control for chat and PDF handling endpoints.
• Audit access to PDFs and chat messages for compliance and debugging.

Testing Checklist

• Unit tests for models and service utilities.
• Integration tests for authentication flows and API endpoints.
• End-to-end tests for the PDF upload, parsing, and chat interaction.
• CI checks for type checking, linting, and test suites.
• Deployment smoke tests in staging before production rollout.

Common Mistakes to Avoid

• Relying on client-side validation alone for security-critical data.
• Exposing raw PDFs without server-side validation and sanitization.
• Overlooking token expiration handling and refresh flow.
• Neglecting proper database migrations during schema changes.

Related implementation resources: AI Use Case for Pet Sitting Businesses Using Timetopet To Match Pet Needs (E.G., Medical Care) with Specialist Sitters and How skill files guide dependency choices for production AI workflows.

FAQ

What is this CLAUDE.md Template for?

A copyable CLAUDE.md file tailored to an Angular Material + FastAPI PDF Chat App stack to guide Claude Code generation.

Which stack does it cover?

Angular Material frontend with a FastAPI backend, PostgreSQL database, and PDF-based chat features.

How should I use the code block?

Copy everything from the # CLAUDE.md line through the end and paste it into your CLAUDE.md file for the project.

How are authentication and security addressed?

JWT-based tokens with OAuth2 flow, server-side validation, and strict input sanitization; secrets come from environment variables only.

Where is the recommended project structure?

The template provides a frontend/backend split with a clear directory tree for Angular Material and FastAPI components.