CLAUDE.md Template: Angular Material + FastAPI Real Time Analytics

Overview

The CLAUDE.md template describes a real-time analytics stack with Angular Material on the frontend and FastAPI on the backend. It provides Claude Code guidance for building a data streaming dashboard with WebSocket updates and robust backend services.

Direct answer: This CLAUDE.md Template provides precise rules and a ready-to-paste Claude Code block that configures roles, architecture, file structure, authentication, validation, and deployment for an Angular Material plus FastAPI real-time analytics app.

When to Use This CLAUDE.md Template

• When you want a copyable Claude Code guide for building a real-time analytics dashboard using Angular Material for UI and FastAPI for API and WebSocket backend.
• When you need a strict file structure, validation, and deployment rules to prevent architecture drift.
• When your project requires WebSocket streaming and a simple pub/sub messaging pattern with Redis.

Copyable CLAUDE.md Template

# CLAUDE.md
Project Role: Full-stack Developer for Angular Material plus FastAPI Real-Time Analytics
Architecture Rules:
- Separate frontend and backend; frontend communicates via REST and WebSocket endpoints.
- Use a lightweight message broker for real-time updates via WebSocket channels.
- Backend handles data persistence; avoid direct database access from the frontend.

File Structure Rules:
- Frontend under frontend with Angular Material modules organized by feature.
- Backend under backend with FastAPI routers and schemas.
- Docker support via docker-compose.yaml.

Authentication Rules:
- Use OAuth2 Password flow with JWT access tokens for API authentication.
- Frontend uses HttpClient with JWT token and a route guard to protect analytics routes.

Database Rules:
- PostgreSQL for primary data and Redis for pub/sub streams and caching.
- Use Pydantic models for validation; ensure migrations.

Validation Rules:
- All inputs validated by Pydantic on the backend and by Angular forms on the frontend.
- Server-side validation must reject invalid data and log details for tracing.

Security Rules:
- HTTPS enforced; CSRF protections as appropriate to token-based auth.
- Do not cache sensitive data; ensure proper CORS and security headers.

Testing Rules:
- Backend: pytest for endpoints; tests for WebSocket streams.
- Frontend: Angular tests (Jasmine/Karma) and Cypress for end-to-end tests.
- CI runs linting, unit tests, and e2e tests.

Deployment Rules:
- Docker Compose with frontend and backend services; environment variables via .env.
- Use TLS termination at the edge; secure storage for secrets.
- Production databases and Redis should be separate services.

Things Claude Must Not Do:
- Do not generate code that bypasses authentication.
- Do not connect frontend directly to the database.
- Do not rely on in-memory persistence for real-time data in production.

Recommended Project Structure

frontend/
  src/
    app/
      modules/
      shared/
      features/
  angular.json
  package.json
backend/
  app/
    main.py
    routers/
    models/
    schemas/
requirements.txt
docker-compose.yml

Core Engineering Principles

• Explicit contracts between frontend and backend via typed interfaces (Pydantic for backend, TypeScript interfaces for frontend).
• Small, testable units with clear responsibilities; avoid monolithic connectors.
• Reliable real-time data flow via WebSocket with a predictable message schema.
• Secure by default: minimal surface area, secrets isolated, minimal permissions.

Code Construction Rules

• Frontend uses Angular Material components (MatTable, MatCard, MatTooltip) with responsive layout.
• Backend: FastAPI with Pydantic models; clean routers; dependency injection for auth and DB sessions.
• Real-time: WebSocket endpoint for streaming; server broadcasts to subscribed clients.
• Data persistence: PostgreSQL with migrations; Redis for pub/sub and temporary storage.
• Validation: Strict type validation on both sides; reject malformed payloads.
• Security: JWT tokens; short-lived access tokens; refresh strategy; CSP safe defaults.
• Testing: pytest for backend; Jest/Angular testing for frontend; Cypress for end-to-end tests.
• Deployment: Docker Compose with separate networks; health checks; logs; observability hooks.
• Do not: Hard-code secrets; Allow frontend direct DB access; Use insecure WebSocket without TLS; Bypass authentication.

Security and Production Rules

• Enable TLS; terminate at edge or load balancer; set secure cookies.
• Validate JWTs; enforce roles for analytics data.
• Use input validation, output escaping, and proper CORS controls.
• Secrets stored in environment variables; do not commit keys to repo.

Testing Checklist

• Backend endpoints covered by pytest with fixtures; WebSocket streaming tested with test clients.
• Frontend unit tests with Jasmine/Karma; component tests and service tests.
• End-to-end tests with Cypress; confirm real-time updates render correctly.
• CI runs linting, tests, and builds for both frontend and backend.

Common Mistakes to Avoid

• Assuming real-time data means no persistence; ensure persistence layer is correct.
• Overexposing backend data to the frontend; enforce fine-grained permissions.
• Ignoring WebSocket reconnection and backpressure handling.
• Neglecting secure token storage in the frontend.

FAQ

What is this CLAUDE.md Template for?

It provides Claude Code guidance for building Angular Material + FastAPI real-time analytics with copyable instructions.

Which files are created by the template?

Frontend modules, backend routers, models, schemas, WebSocket endpoints, and config for OAuth2 + Redis pub/sub.

How is authentication handled?

JWT access tokens with OAuth2 password flow on the backend; route guards on the frontend.

How is real-time data streamed?

WebSocket endpoints in FastAPI publish updates via Redis Pub/Sub to connected clients.

How do I deploy?

Use Docker Compose with separate frontend and backend services, TLS, and environment-based configuration.