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.

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.