Angular Material + FastAPI WebSocket Chat CLAUDE.md Template

Overview

A CLAUDE.md template for Angular Material + FastAPI WebSocket Chat provides a copyable Claude Code starter that codifies architecture, security, testing, and deployment for a real-time chat stack. It helps teams share a single, testable baseline that covers both the Angular Material frontend and the FastAPI backend WebSocket channel.

Direct answer: This page yields a ready-to-paste CLAUDE.md template you can drop into your repo to guide implementation, validation, and deployment for this stack.

When to Use This CLAUDE.md Template

• Kickstart a real-time chat application with a polished Angular Material UI and a FastAPI WebSocket backend.
• Provide a single source of truth for architecture, security, and testing practices.
• Onboard new engineers quickly with a reproducible starter and Claude Code guidelines.
• Ensure consistent deployment and production rules across environments.

Copyable CLAUDE.md Template

# CLAUDE.md

Project role:
- You are Claude Code, the AI assistant responsible for producing a complete CLAUDE.md template for an Angular Material + FastAPI WebSocket Chat project.

Architecture rules:
- Frontend: Angular Material UI (v16+), modular design, state management optional (NgRx or Signals).
- Backend: FastAPI with WebSocket endpoint at /ws/chat, using a simple JSON message contract.
- Real-time channel: WebSocket with clean message framing and ping/pong keep-alives.
- Deployable as separate services with a shared secure API surface.

File structure rules:
- frontend/
  - src/app/ (components, services, guards)
  - angular.json, tsconfig.json
  - assets/
- backend/
  - main.py
  - ws/ (websocket handlers)
  - models/ (pydantic schemas)
  - requirements.txt

Authentication rules:
- Backend requires a signed JWT token passed in the WebSocket connection query or subprotocol.
- Frontend attaches valid token to connection initialization; refresh tokens handled via REST flow.
- Do not accept unauthenticated WebSocket connections.

Database rules:
- Use Postgres to persist users and messages.
- Messages table: id, user_id, content, timestamp, room_id.
- Do not store raw HTML; sanitize and escape on entry.

Validation rules:
- Validate message length (1-1000 chars) and disallow control characters except newline.
- Validate user_id exists and is active before accepting message.

Security rules:
- Enforce HTTPS/WSS in all environments.
- Validate and sanitize all incoming data; blacklist dangerous content.
- Limit WebSocket origins to configured frontends.

Testing rules:
- Unit tests for frontend components (Angular) and backend (FastAPI) handlers.
- Integration tests for WebSocket chat flow using pytest-asyncio.
- End-to-end tests simulate user join, message send, and receipt.

Deployment rules:
- Docker compose with frontend and backend services; TLS termination in fronting proxy.
- Environment variable usage for secrets; avoid hard-coded credentials.
- CI: run tests on PR; linting and type checks enforced.

Things Claude must not do:
- Do not bypass authentication or security checks.
- Do not produce inline database credentials or secrets.
- Do not use unsafe eval or dynamic imports.

Recommended Project Structure

frontend/
  src/
    app/
      components/
      services/
      guards/
    index.html
    main.ts
  angular.json
  package.json
backend/
  main.py
  ws/
  models/
  requirements.txt
docker-compose.yml
Dockerfile.frontend
Dockerfile.backend

Core Engineering Principles

• Explicit typing and clear contracts between frontend and backend.
• Separation of concerns across UI, API, and WebSocket layers.
• Idempotent, well-tested operations for message handling and delivery.
• Validation, sanitization, and least-privilege access by default.
• Repeatable deployments with reproducible environments.

Code Construction Rules

• Use Angular Material components for a consistent UI; avoid custom components without design review.
• Leverage FastAPI's WebSocket support with a compact message schema.
• Validate messages with Pydantic models on the server side; sanitize input before storage or display.
• Attach JWT tokens on WebSocket connect and validate per message basis if needed.
• Keep WebSocket logic isolated in ws/ with min business logic in a separate service layer.
• Use environment-based configuration for endpoints and CORS; avoid hard-coded URLs.

Security and Production Rules

• Enforce TLS for all traffic; use WSS for WebSocket endpoints.
• Validate allowed origins; restrict cookie and header usage to prevent CSRF.
• Implement token rotation and short-lived access tokens with refresh flow.
• Limit message rate and implement simple anti-spam measures.
• Audit logs for authentication events and message delivery failures.

Testing Checklist

• Unit tests for Angular components and services; backend models and endpoints.
• WebSocket flow tests: connect, authenticate, send message, receive broadcast.
• Integration tests across frontend-backend boundary with a test WebSocket server.
• Deployment smoke tests: service startup, health checks, TLS termination verified.

Common Mistakes to Avoid

• Skipping frontend-backend contract validation; mismatched message schemas.
• Opening unsecured WebSocket endpoints or lax origin checks.
• Storing unescaped HTML in the database; risk of XSS in UI.
• Hard-coding secrets or credentials in code or config.
• Neglecting test coverage for WebSocket paths.

FAQ

• What is a CLAUDE.md Template for this stack? A copyable CLAUDE.md template that codifies architecture, security, testing, and Claude Code instructions for a frontend Angular Material UI with a FastAPI WebSocket backend.
• Which stack is covered by this template? Angular Material frontend + FastAPI WebSocket backend for a real-time chat app.
• Where should I paste the generated Claude Code? Paste into CLAUDE.md at the repository root for this stack.
• How do I run the stack locally? Run ng serve for the frontend and uvicorn for the backend; ensure WS connectivity on the configured host/port.
• What are common security considerations? Use HTTPS/WSS, validate input, restrict origins, and enforce token-based authentication for WebSocket messages.