CLAUDE.md Template — Angular Material + FastAPI RAG App

Overview

The CLAUDE.md template is a copyable Claude Code instruction block designed for a stack that combines Angular Material on the frontend with a FastAPI backend and a Retrieval-Augmented Generation (RAG) data layer. It provides a deterministic, action-oriented blueprint that helps Claude Code generate scaffolding, wiring, and guardrails for this exact stack. This CLAUDE.md template is specialized for an Angular Material + FastAPI RAG app and includes concrete project structure, validation, security, and testing guidance that you can paste as-is into CLAUDE.md.

When to Use This CLAUDE.md Template

• You are building an AI-assisted web app with an Angular Material UI and a FastAPI REST API behind a RAG component.
• You want a copyable instruction block that yields consistent project scaffolding, data flow, and guardrails.
• You need stack-specific rules for authentication, validation, security, and deployment that CLAUDE Code can follow without guesswork.

Copyable CLAUDE.md Template

# CLAUDE.md
Project: Angular Material frontend + FastAPI backend + RAG data layer
Role: You are Claude, a code assistant that outputs a precise CLAUDE.md template for this stack
Architecture rules:
- Frontend uses Angular Material components and RxJS streams. Separate UI from business logic and data access. Use typed forms and guards for route protection.
- Backend uses FastAPI with Pydantic models for all input/output validation. JWT-based auth and OAuth2 flows where applicable. Expose a minimal API surface with clear versioning and dependency management.
- Data layer uses PostgreSQL with pgvector for embeddings and a simple Redis cache for hot data. Ensure migrations are versioned and repeatable.
- RAG flow: user question → retrieve relevant embeddings from vector store → compose prompt with retrieved context → call LLM endpoint → format answer back to frontend with provenance.
File structure rules:
- Keep frontend under client/ and backend under server/; data resides under data/; avoid cross-cutting folders.
- Frontend: client/src/app contains feature modules, components, and services. Backend: server/app contains api, core, db, and models.
- Do not commit secrets or raw credentials in code. Use environment variables and secret managers.
Authentication rules:
- Use OAuth2PasswordBearer or JWT-based authentication for API endpoints. Do not rely on session cookies for API access.
- Frontend stores tokens securely (httpOnly cookies or secure storage per framework guidance) and sends tokens via Authorization headers.
Database rules:
- PostgreSQL with pgvector for embeddings. Use typed queries and parameterized statements. Enforce least privilege for database roles.
Validation rules:
- All inputs/outputs validated with Pydantic models. Use strict type checking and explicit field requirements. Reject unknown fields.
Security rules:
- Enable CORS only for allowed origins. Enforce HTTPS in all environments. Sanitize all inputs; avoid eval and dynamic code execution. Do not ship default secrets.
Testing rules:
- Unit tests for models and data transforms. Integration tests for API endpoints. End-to-end tests for the RAG flow using a mocked vector store. Ensure tests run in CI.
Deployment rules:
- Use Docker Compose or Kubernetes. Separate services, health checks, resource limits, and rolling updates. Secrets managed via environment or secret store.
Things Claude must not do:
- Do not generate code that exposes secrets or uses insecure defaults. Do not bypass authentication or validation. Do not assume non-existent endpoints or dependencies.

Recommended Project Structure

project/
  client/
    src/
      app/
        components/
        services/
      index.html
      main.ts
    angular.json
    package.json
  server/
    app/
      main.py
      api/
        v1/
      models/
      core/
      db/
      dependencies/
    Dockerfile
    requirements.txt
  data/
    embeddings/
    vectors/
  docker-compose.yml

Core Engineering Principles

• Clarity and maintainability: write explicit code and keep responsibilities separated between frontend and backend.
• Type safety and validation: enforce strict input/output models with Pydantic and Angular types.
• Security by default: implement authentication, validation, CORS rules, and secrets management from the start.
• Reproducibility: version migrations, deterministic prompts, and documented environment configuration.
• Observability: structured logging, metrics, and tracing for API and RAG flows.
• Performance focus: lazy loading, caching for hot data, and efficient vector retrieval.

Code Construction Rules

• Frontend must use Angular Material components and Angular idioms (modules, services, guards, and typed forms).
• Backend must expose stable API contracts via Pydantic models and FastAPI routers with dependency injection.
• All database queries must be parameterized. Do not build SQL with string concatenation.
• The RAG pipeline should separate retrieval, prompt assembly, and response rendering with clear boundaries.
• Do not hard-code secrets. Use environment variables and a secured secret store.
• Do not bypass authentication on protected endpoints. Do not expose admin endpoints publicly.

Security and Production Rules

• Enable HTTPS in all environments and configure TLS certificates via your hosting platform.
• Restrict CORS to known frontend origins.
• Validate and sanitize all user inputs. Avoid eval and unsafe dynamic code execution.
• Rotate and manage API keys and database credentials through a secret manager.
• Implement rate limiting on API endpoints and monitor for abuse in the RAG flow.

Testing Checklist

• Unit tests for Pydantic models and Angular services.
• Integration tests for FastAPI endpoints with mocked dependencies.
• End-to-end tests for the RAG path using a stubbed vector store.
• CI checks for linting, typing, and test success; ensure tests run on PRs.
• Deployment tests for docker-compose or k8s manifests with health checks.

Common Mistakes to Avoid

• Mixing frontend and backend concerns in a single module.
• Omitting input validation or returning unstructured errors from API endpoints.
• Exposing internal URLs or secrets in the CLAUDE.md template output.
• Not isolating the vector store from public API surfaces.
• Skipping CI tests for the RAG flow and data layer integration.

FAQ

What is a CLAUDE.md template

A copyable Claude Code instruction block tailored to a stack that defines project rules, file structure, security, testing, and deployment.

Why Angular Material + FastAPI for a RAG app

Angular provides a polished UI with Material components; FastAPI offers fast, typed endpoints; RAG adds intelligent retrieval for user queries.

How do I run this locally

Set up a docker-compose stack or run separate services for frontend and backend; load environment variables; run migrations and seed data if needed.

How to customize the RAG pipeline

Adjust the retrieval step to your vector store, modify the prompt construction to include context, and route results back to the frontend with provenance.

Where to deploy

Use your chosen cloud provider with a container-based deployment; ensure TLS, secrets management, and autoscaling for the API and RAG components.