Angular Material + FastAPI Streaming Chat CLAUDE.md Template

Overview

CLAUDE.md template is a copyable Claude Code instruction block that you paste into CLAUDE.md to guide Claude in building and wiring a stack. This page provides a copyable CLAUDE.md template for an Angular Material frontend with a FastAPI streaming chat backend.

Direct answer: This CLAUDE.md template yields a ready-to-paste Claude Code block for building a real-time chat app with Angular Material and a FastAPI streaming backend.

When to Use This CLAUDE.md Template

• Starting a new project using Angular Material for UI and FastAPI for the backend streaming chat.
• Documenting architecture and Claude Code rules to reduce drift between frontend and backend.
• Sharing a consistent, executable Claude Code block across team members.
• Onboarding new engineers with stack-specific guidelines and constraints.

Copyable CLAUDE.md Template

# CLAUDE.md

Project role: You are Claude Code assistant guiding the full-stack for an Angular Material frontend and a FastAPI streaming chat backend. Generate code and design decisions that respect both UI and API constraints.

Architecture rules:
- Frontend is Angular Material based and communicates with the backend via REST for non-streams and WebSocket for streaming chat.
- Backend is FastAPI with a dedicated streaming endpoint for chat messages.
- Use typed data contracts in JSON for messages and events.
- Do not mix UI concerns into backend logic; keep boundaries clear.
- Provide concise, testable code blocks and wiring guidance for both sides.

File structure rules:
- frontend/ contains the Angular Material app with components, services, and routing.
- backend/ contains FastAPI app with routers, models, schemas, and dependencies.
- shared/ contains shared types and DTOs used by both sides.
- No unrelated boilerplate from other stacks.

Authentication rules:
- Use JWT Bearer tokens in Authorization headers for protected endpoints.
- Validate tokens on all sensitive routes with a centralized dependency.
- Do not expose secret keys in frontend code; fetch ephemeral tokens from a secure auth service.

Database rules:
- Use PostgreSQL; define chat messages, users, and sessions tables with proper foreign keys.
- Use SQLAlchemy models and Alembic migrations.
- Do not rely on in-memory or SQLite in production.

Validation rules:
- Backend: Pydantic models for request/response validation.
- Frontend: Reactive forms with client-side validation and error handling.
- Validate all inputs to prevent invalid data and injection.

Security rules:
- Enforce HTTPS and secure WebSocket connections (wss://).
- Implement CORS with a minimal allowlist.
- Sanitize chat content and escape user input in the UI.
- Implement rate limiting on chat messages per user/IP.

Testing rules:
- Backend: pytest tests for endpoints and streaming behavior.
- Frontend: Jest or Karma tests for components and services.
- Include integration tests that simulate a streaming session.

Deployment rules:
- Docker Compose with frontend and backend services; multi-stage builds; environment variables for secrets.
- Use a reverse proxy in production (e.g., Nginx) and enable TLS termination.
- Statically type all contracts to minimize runtime errors.

Things Claude must not do:
- Do not reveal secret keys or credentials.
- Do not bypass authentication checks.
- Do not hard-code production database URLs.
- Do not generate code that bypasses proper input validation or security checks.

Recommended Project Structure

frontend/
  src/
    app/
      components/
      services/
      app.module.ts
      app.component.ts
    assets/
    environments/
  angular.json
  package.json
  tsconfig.json
backend/
  app/
    main.py
    routers/
      chat.py
    models/
    schemas/
    dependencies/
  requirements.txt
  Dockerfile
  docker-compose.yml
shared/
  types/
.env.example

Core Engineering Principles

• Clear separation of concerns between frontend UI and backend API.
• End-to-end typing with TypeScript on the frontend and Pydantic on the backend.
• Streaming-first backend design for real-time chat experiences.
• Observability: structured logging and metrics for streaming endpoints.
• Security by default: validate inputs, protect endpoints, and manage secrets safely.

Code Construction Rules

• Frontend must use Angular Material components and reactive forms for chat input.
• Backend must expose a WebSocket /ws/chat endpoint for streaming and a REST /messages for history.
• All data contracts must be defined in TypeScript interfaces and Pydantic models and kept in sync.
• Use dependency injection for services (auth, db, chat) in FastAPI.
• Do not bypass token validation or skip input validation for performance.

Security and Production Rules

• Enforce TLS in all production deployments and use a reverse proxy with TLS termination.
• Limit CORS to trusted origins only.
• Store secrets in environment variables or secret managers; never hard-code them.
• Implement token rotation and short-lived access tokens with refresh tokens.
• Enable input sanitization and output escaping to prevent XSS/SQL injection.

Testing Checklist

• Unit tests for FastAPI endpoints and Pydantic models.
• Streaming tests that verify message chunks are received in order.
• Frontend unit tests for Angular components and services.
• End-to-end tests that simulate a user login, chat, and message history fetch.
• CI checks to ensure type safety and lint rules pass.

Common Mistakes to Avoid

• Assuming in-memory data is sufficient for production; use a real database.
• Skipping token validation on streaming endpoints.
• Overloading the frontend with business logic; keep it focused on presentation.
• Ignoring input validation on the backend for streaming data.

FAQ

What is the purpose of this CLAUDE.md Template?

It provides a copyable Claude Code instruction block to guide Claude in building a streaming chat app with Angular Material and FastAPI.

Does this template support streaming chat with FastAPI?

Yes, it designs a WebSocket streaming endpoint and Pydantic models for streaming messages.

How should authentication be handled?

Use JWT Bearer tokens in the Authorization header; backend validates tokens on protected endpoints.

Where should I customize database configuration?

Configure PostgreSQL in backend/config and SQLAlchemy models; use Alembic for migrations.

How do I deploy this stack?

Use docker-compose with frontend and backend services; ensure environment variables are supplied and TLS is configured.