CLAUDE.md Template: Angular Material + FastAPI Observability Dashboard

Overview

This CLAUDE.md template is designed for building an Angular Material + FastAPI observability dashboard. It provides concrete Claude Code instructions, stack-specific rules, and a ready to paste CLAUDE.md block to bootstrap the project with proper architecture, security, and testing considerations. Direct answer: you can paste the included CLAUDE.md block to initialize the stack with Angular Material frontend and FastAPI backend.

When to Use This CLAUDE.md Template

• You need a reproducible CLAUDE.md block for an observability UI built with Angular Material.
• You want production-ready patterns for FastAPI telemetry and dashboards.
• You require stack-specific rules for file structure, authentication, validation, and deployment.

Copyable CLAUDE.md Template

# CLAUDE.md
Project role: Platform Engineer responsible for an Angular Material + FastAPI observability dashboard

Architecture rules:
- Frontend and backend are separate services with a shared API contract
- Use REST endpoints with clear versioning
- Telemetry should be captured via a lightweight agent on both sides

File structure rules:
- /frontend contains all Angular Material code
- /backend contains FastAPI app code
- /infrastructure holds deployment manifests

Authentication rules:
- JWT/OAuth2 for API access from the frontend
- Frontend stores tokens in memory with refresh tokens rotated regularly

Database rules:
- Prefer PostgreSQL for relational data and time-series for metrics where applicable
- Do not store raw logs in relational DB; export to a log sink when possible

Validation rules:
- Use Pydantic models in FastAPI for all request/response bodies
- Use Angular validators and reactive forms for frontend inputs

Security rules:
- Enforce CORS only for the Angular frontend domain
- Enable TLS in production; never hardcode secrets

Testing rules:
- Unit tests for frontend components and backend routers
- Integration tests for API endpoints and telemetry endpoints
- End-to-end tests for the dashboard flows

Deployment rules:
- Dockerize frontend with npm run build and serve via a lightweight server
- Dockerize backend with uvicorn and enable workers
- Use docker-compose for local development and K8s manifests for production

Things Claude must not do:
- Do not embed secrets in code blocks
- Do not bypass authentication checks
- Do not assume a single database fits all telemetry scenarios

Recommended Project Structure

/frontend
  /src
    /app
      /core
      /dashboard
      /widgets
      /shared
  angular.json
  package.json
  tsconfig.json
/backend
  /app
    /api
    /models
    /services
    /routers
  main.py
  requirements.txt
  Dockerfile
/infrastructure
  docker-compose.yml

Core Engineering Principles

• Separation of concerns between frontend and backend with a clear API contract
• Type safety across both layers using TypeScript on the frontend and Pydantic on the backend
• Observability by design: emit metrics, traces, and logs consistently
• Security by default: least privilege, proper authentication, and validated inputs
• Automated tests at unit, integration, and end-to-end levels

Code Construction Rules

• Frontend uses Angular Material components with a consistent design system
• Backend endpoints are typed with Pydantic models and FastAPI routers are modular
• Environment configuration is externalized; no secrets in code
• Telemetry endpoints are read-only for dashboards unless explicitly authorized
• Code formatting adheres to project-wide linters and formatters

Security and Production Rules

• JWT-based authentication for API access; refresh tokens rotate
• CORS restricted to the frontend domain; TLS enabled in prod
• Audit logging for auth events; avoid logging sensitive payloads
• Dependabot or similar tools keep dependencies up to date

Testing Checklist

• Unit tests for frontend components and backend models
• Integration tests for API routes and telemetry endpoints
• End-to-end tests for dashboard user flows
• CI checks for linting, type checking, and test coverage
• Deployment verification in staging environment

Common Mistakes to Avoid

• Skipping type validation on API inputs
• Hardcoding secrets or credentials in code blocks
• Overloading the frontend with excessive telemetry without sampling
• Ignoring production security best practices in templates

FAQ

1. What is a CLAUDE.md template? A copyable Claude Code instruction block designed to initialize a stack-specific CLAUDE.md file.
2. Which stack does this template cover? Angular Material frontend with a FastAPI backend observability dashboard.
3. How do I use the copyable CLAUDE.md block? Copy the block under Copyable CLAUDE.md Template into CLAUDE.md in your repo and adapt paths and tokens.
4. Can I customize for my environment? Yes, adjust project roles, endpoints, tokens, and environment-specific configs within the template.
5. What security considerations are included? The template prescribes JWT-based auth, restricted CORS, and TLS for production; never embed secrets.