Angular Material + FastAPI AI Chatbot CLAUDE.md Template

Overview

CLAUDE.md template is a copyable Claude Code instruction set designed to scaffold a complete AI chatbot project using Angular Material on the frontend and FastAPI on the backend. This page provides a ready-to-paste CLAUDE.md block and stack-specific guidance for a production-ready project.

Direct answer: This CLAUDE.md Template delivers a ready-to-paste Claude Code block, stack-specific structure, and concrete rules to build, test, and deploy an Angular Material + FastAPI AI chatbot using Claude Code.

When to Use This CLAUDE.md Template

• When starting a new Angular Material + FastAPI AI chatbot project and you want a single source of truth for prompts and constraints.
• When you need a copyable CLAUDE.md to onboard teammates quickly.
• When documenting architecture, file layout, and security rules for Claude Code in this stack.
• When preparing for production deployment with tests and security checks.

Copyable CLAUDE.md Template

# CLAUDE.md
Project: Angular Material + FastAPI AI Chatbot
Role: You are a Claude Code automation assistant responsible for producing a complete, production-ready CLAUDE.md template for the given stack.
Architecture rules:
- Frontend is Angular Material and communicates with a FastAPI backend via REST endpoints.
- Maintain a clean separation between frontend and backend; avoid cross-domain state leakage.
- All Claude Code prompts must be isolated from business logic and not perform direct data access.
File structure rules:
- Frontend under frontend/ with src/app structure and proper module separation.
- Backend under backend/ with app/ containing main.py, routers, and core modules.
- Common prompts under claude/ prompts directory for reuse.
Authentication rules:
- Backend uses JWT tokens in Authorization header: Bearer <token>.
- Do not store tokens in local storage; prefer HttpOnly cookies for session tokens.
Database rules:
- Use PostgreSQL via SQLAlchemy and Alembic for migrations.
- Never store secrets in source code or logs.
Validation rules:
- Use Pydantic models on the FastAPI side; validate inputs strictly.
- Validate input length, allowed characters, and schema shapes.
Security rules:
- Enforce HTTPS in production; configure CORS for allowed origins.
- Do not expose sensitive environment values in API responses.
Testing rules:
- Unit tests for utilities and data models; integration tests for chat endpoints.
- CLI commands tested with deterministic fixtures; frontend tests for components.
Deployment rules:
- Docker Compose with frontend, backend, and Postgres services; include migrations.
- Use environment files for secrets; ensure variables are not checked in.
Things Claude must not do:
- Do not disclose secrets or tokens.
- Do not bypass authentication or attempt database access from Claude prompts.
- Do not generate non-deterministic prompts that rely on external network calls during prompt generation.

Recommended Project Structure

frontend/
  src/
    app/
      components/
      services/
      app.module.ts
      app.component.ts
    assets/
  index.html
  angular.json

backend/
  app/
    main.py
    models.py
    routers/
      chat.py
    core/
      config.py
      security.py
  requirements.txt
  Dockerfile

Core Engineering Principles

• Clear contract between Claude Code prompts and implementation.
• Idempotent and deterministic outputs for repeatable results.
• Security by default with strict access controls and secret management.
• Documentation-driven development with explicit rules and expectations.
• Tests-first approach; codify checks in CLAUDE.md and code.
• Modular, scalable structure that cleanly separates frontend and backend concerns.

Code Construction Rules

• Frontend should be TypeScript (Angular) and use Angular Material components for UI parity.
• Backend should be Python 3.11+ with FastAPI and Pydantic models.
• Endpoints must be explicit and versioned (e.g., /api/v1/chat).
• CLS and function-level documentation for Claude Code prompts.
• Use type hints and strict input validation in all handlers.
• Do not import large libraries just to satisfy a check; prefer minimal, well-supported packages.
• Do not hard-code secrets in code or prompts.

Security and Production Rules

• Enforce HTTPS in production; configure HSTS and secure cookies.
• JWT-based authentication with short-lived access tokens and refresh tokens.
• Strict CORS with a small allowed origins list; keep it in environment config.
• Secret management via environment variables; never commit secrets to repo.
• Validation at all boundaries; never trust client input beyond token verification.

Testing Checklist

• Frontend: unit tests for components and services; end-to-end tests for chat UI.
• Backend: unit tests for models and utilities; integration tests for API endpoints and chat flow.
• CI/CD: run tests on push; perform container image scan and security checks.

Common Mistakes to Avoid

• Assuming Claude Code will fetch secrets or reach external services during prompt processing.
• Skipping input validation or overtrusting client inputs.
• Mixing frontend and backend responsibilities or leaking tokens in logs.
• Ignoring deployment, migrations, and security checks in the template.

FAQ