CLAUDE.md Template: Angular Material + FastAPI Vector Search

Overview

A CLAUDE.md Template page tailored for a stack combining Angular Material on the frontend with a FastAPI backend that uses a vector search backend (e.g., Weaviate or Pinecone). This page provides a copyable CLAUDE.md block that guides Claude Code to generate, validate, and deploy a complete vector-search app across the two tiers with clear constraints, security rules, and testing checks.

Direct answer: This template yields a ready-to-paste CLAUDE.md block that enforces a consistent architecture, project structure, and production-readiness guidelines for an Angular Material + FastAPI vector-search solution.

When to Use This CLAUDE.md Template

• You are building a full-stack app with Angular Material UI and a FastAPI API that supports vector search against a dedicated vector store (Weaviate or Pinecone).
• You want a single, copyable Claude Code instruction block to accelerate boilerplate generation, validation, and deployment patterns.
• You need stack-specific constraints (folder layout, auth flow, data models, and tests) embedded in a CLAUDE.md template for repeatable onboarding.

Copyable CLAUDE.md Template

# CLAUDE.md

Project role:
- You are Claude Code, a CLAUDE.md template engineer. Your task is to output a single, copyable CLAUDE.md template for an Angular Material + FastAPI Vector Search stack. Do not add unrelated tech. Your output should be paste-ready for developers.

Architecture rules:
- Frontend: Angular Material SPA communicates with a REST/GraphQL API built by FastAPI.
- Backend: FastAPI exposes endpoints for document ingestion, embedding generation, and vector search queries.
- Vector store: Use Weaviate or Pinecone as the vector database; all embeddings originate from backend services.
- Auth: Use OAuth2 / JWT Bearer tokens; frontend stores tokens securely; backend validates tokens on protected routes.
- Data flow: Client sends search query; backend computes or fetches embeddings; backend queries vector store and returns ranked results to frontend.
- Observability: Structured logging, tracing via OpenTelemetry; error handling must avoid leaking secrets.

File structure rules:
- Frontend in /frontend (Angular Material)
- Backend in /backend (FastAPI)
- Vector DB configs in /vector
- All environment variables managed via .env.example and deployment configs
- Do not mix frontend and backend code in the same module tree

Authentication rules:
- Use OAuth2 Password Flow or PKCE for SPA-to-API auth; issue access tokens with short lifetimes (15–60 minutes) and refresh tokens where appropriate.
- Do not expose secret keys in frontend code; fetch tokens from a secure auth server.
- Validate tokens on every protected endpoint; ensure roles/scopes gate access.

Database rules:
- Use a dedicated vector store (Weaviate or Pinecone); do not store vectors in a relational DB.
- Ensure embeddings are generated server-side; avoid client-side embedding logic.
- Apply schema validation for vector data; consistency checks on id, vector, and metadata.

Validation rules:
- Backend: Pydantic models with strict field types; request bodies validated before processing.
- Input: Validate on both client and server; sanitize strings; enforce max lengths.
- Output: Normalize results; include id, score, and metadata in vector search responses.

Security rules:
- Do not expose secrets in code or repos; use environment vars and secret managers.
- Enable CORS only for trusted origins; disable debug in prod.
- Use HTTPS in all environments; secure cookies for auth sessions.
- Protect against injection, path traversal, and data exfiltration by validating inputs and escaping outputs.

Testing rules:
- Backend: unit tests for models, services, and endpoints using pytest; mock vector store interactions.
- Integration: end-to-end tests that spawn a minimal vector store and verify ingestion and search flows.
- Frontend: component and e2e tests with Angular testing tools; ensure UI displays results and handles errors gracefully.
- CI: run tests on pull requests; require tests to pass before merging.

Deployment rules:
- Dockerized: separate services for frontend, backend, and vector store config; use docker-compose or Kubernetes manifests.
- Secrets: load via environment; use build-time ARGs only for non-secret values; secret rotation supported.
- Rollback: tag releases; keep previous image versions; health checks on startup.

Things Claude must not do:
- Do not hard-code secrets or API keys.
- Do not assume Pinecone is installed locally if using Weaviate, or vice versa.
- Do not bypass authentication or authorization checks.
- Do not produce insecure CORS or browser-based embeddings without server-side controls.
- Do not generate code that directly reads from or writes to production databases without proper validation and access controls.

# End CLAUDE.md block

Recommended Project Structure

project-root/
├── frontend/
│   ├── src/
│   │   ├── app/
│   │   ├── assets/
│   │   └── styles/
│   ├── angular.json
│   └── package.json
├── backend/
│   ├── app/
│   │   ├── api/
│   │   ├── core/
│   │   ├── models/
│   │   └── services/
│   ├── main.py
│   ├── requirements.txt
│   └── tests/
├── vector/
│   ├── config/
│   └── schemas/
└── docker-compose.yml

Core Engineering Principles

• Keep frontend and backend concerns separated with clean boundaries.
• Prefer typed contracts (TypeScript on the frontend, Pydantic on the backend).
• Design for testability first; write tests before implementing features.
• Adopt a single source of truth for embeddings and metadata.
• Automate deployment, observability, and secret management from day one.

Code Construction Rules

• Frontend actions must be pure UI; backend must handle embeddings and vector queries.
• Use FastAPI routers for versioned endpoints (v1, v2).
• Embed vectors in Weaviate or Pinecone via backend services; avoid client-side embedding generation.
• Validate all inputs with strict models; never trust client payloads.
• Keep API responses consistent: { id, score, metadata, results }.

Security and Production Rules

• Use HTTPS and secure cookie handling for SPA auth flows.
• Rotate and protect tokens; implement token revocation if supported by the auth provider.
• Limit CORS to known origins; log and monitor failed auth attempts.
• Do not leak internal error details to clients; generic messages with server-side logging.

Testing Checklist

• Unit tests for all Pydantic models and FastAPI endpoints.
• Integration tests that mock vector store interactions and verify full data flow.
• Frontend tests for components, services, and UI flows; end-to-end tests for the search experience.
• CI: run linting, type checks, unit tests, and integration tests on PRs.
• Production checks: health checks, load tests, and metrics collection configured.

Common Mistakes to Avoid

• Hard-coding endpoints or keys; always use environment/config management.
• Over-fetching data or performing heavy embeddings on the client.
• Ignoring vector store schema or embedding dimension mismatches.
• Neglecting authentication flow and token security in SPA scenarios.

FAQ