Angular Material + FastAPI Monitoring Dashboard CLAUDE.md Template

Overview

CLAUDE.md template for building a monitoring dashboard with Angular Material on the frontend and FastAPI on the backend. This stack-focused CLAUDE.md Template provides a copyable Claude Code block and a starter project that enforces observability, secure APIs, and clean UI components.

When to Use This CLAUDE.md Template

• When starting a new monitoring dashboard project with Angular Material on the frontend and FastAPI on the backend.
• When you want a stack-specific CLAUDE.md Template that includes a copyable Claude Code block for rapid iteration.
• When you need production-ready rules for architecture, security, testing, and deployment.

Copyable CLAUDE.md Template

# CLAUDE.md

Project role: Full-Stack Monitoring Dashboard Engineer (Angular Material + FastAPI)

Architecture rules:
- Build a two-tier architecture: Angular Material SPA frontend (client/) communicates with a FastAPI backend (server/) through REST/JSON endpoints. Use a PostgreSQL database for persistence and a lightweight metrics exporter for observability.
- Frontend must consume only defined API endpoints with strict typing and error handling. Backend must validate all inputs using Pydantic models.
- All secrets and credentials must be supplied via environment variables or secret managers; never hard-code credentials.

File structure rules:
- client/ angular-material-dashboard/
- server/ fastapi-dashboard/
- common/ shared models or DTOs if needed

Authentication rules:
- Use OAuth2 with JWT (JWT access token short-lived, refresh token long-lived). Use FastAPI's OAuth2PasswordBearer on the backend and HttpOnly cookies for refresh tokens when possible.
- Frontend stores tokens in memory and uses an HttpOnly cookie for refresh; include token in Authorization header for API requests.

Database rules:
- PostgreSQL database; SQLAlchemy for ORM in FastAPI; Alembic for migrations.
- Metrics and event data separated by schemas. Use indices on timestamp fields for fast range queries.

Validation rules:
- Pydantic models on FastAPI; strict typing; custom validators for critical fields.
- Frontend TypeScript interfaces must mirror backend schemas.

Security rules:
- Enforce HTTPS, CORS with a strict allowlist, rate limiting per IP, and HSTS.
- Sanitize inputs and escape outputs; enable Content Security Policy.

Testing rules:
- Backend: unit tests for each endpoint, tests for authentication flows, and integration tests that cover DB interactions.
- Frontend: unit tests for components and services; E2E tests for critical user journeys (login, dashboard drill-down).

Deployment rules:
- Docker-based deployment with docker-compose for local development; Kubernetes manifests for production. Use multi-stage Docker builds to minimize image size.
- CI/CD pipeline that runs tests on merge and builds docker images tagged with commit SHAs.

Things Claude must not do:
- Do not bypass authentication or expose API endpoints publicly.
- Do not couple frontend to a hard-coded backend URL; read from environment/config at runtime.
- Do not generate or commit secret keys to source control.

Recommended Project Structure

client-angular-dashboard/
  src/
    app/
      components/
        dashboard/
        widgets/
      services/
      models/
    index.html
    main.ts
  angular.json
  package.json
  tsconfig.json
server-fastapi-dashboard/
  app/
    main.py
    api/
      v1/
        endpoints/
        dependencies/
    models/
    core/
    db/
  requirements.txt
  alembic/
  alembic.ini
  Dockerfile
  docker-compose.yml
config/
  deployment.env

Core Engineering Principles

• Type-safe by default: enforce strict typing across frontend and backend.
• Clear contracts: define API schemas and DTOs upfront using Pydantic and TypeScript interfaces.
• Observability: integrate metrics, logging, and health checks from day one.
• Security-first: minimize surface area, validate inputs, and secure tokens.
• Modular design: separate concerns between UI components and API services.
• Test-driven mindset: add unit, integration, and e2e tests early.

Code Construction Rules

• Frontend must use Angular Material components: MatToolbar, MatSidenav, MatCard, MatTable, MatIcon, responsive layouts with Breakpoints.
• Use OnPush change detection and immutable data patterns for performance.
• API calls via HttpClient with Interceptors for auth; handle 401 redirects to login.
• Backend endpoints typed with Pydantic models; use routers and dependency injection.
• Database access via SQLAlchemy; Alembic migrations; connection pooling and proper async support where applicable.
• Validation: validate all inputs on server; mirror schemas on the frontend.
• Observability: expose /metrics endpoints and structured logging; emit events for dashboards.
• Do not hard-code URLs or credentials; use environment-based config.

Security and Production Rules

• Enable HTTPS and HSTS; implement secure cookies and token storage guidelines.
• CORS allowlist should be limited to the frontend domain; avoid wildcard origins in production.
• Use token-based authentication with short-lived access tokens; rotate refresh tokens securely.
• Limit request rate per IP; protect endpoints with proper permissions.
• Audit logging for authentication and data-access events.

Testing Checklist

• Unit tests for FastAPI endpoints with pytest; test input validation and error paths.
• Integration tests that hit the database with a test container or mocked DB.
• Frontend unit tests for components and services; ensure UI logic matches backend data shapes.
• End-to-end tests for login, dashboard rendering, and metric drill-down.
• Deployment tests: docker-compose local, then a staging Kubernetes env.

Common Mistakes to Avoid

• Assuming the frontend can access private backend endpoints without proper auth.
• Neglecting input validation and trusting client-side validation alone.
• Overfetching data; not implementing pagination or query limits on metrics endpoints.
• Ignoring observability; missing health checks and metrics exposure.
• Relying on non-deterministic UI timing in tests; write deterministic tests.

FAQ

What is this CLAUDE.md Template for?

A copyable CLAUDE.md Template that guides building an Angular Material + FastAPI Monitoring Dashboard.

Which stack is covered by this template?

Angular Material frontend and FastAPI backend with PostgreSQL for persistence.

What should I customize?

Project role, architecture, file structure, auth, DB, validation, security, tests, and deployment.

Can I reuse this for other stacks?

Yes, adapt the CLAUDE.md block and project structure to match your stack while preserving the same sections.

Where can I find related templates?

See the CLAUDE.md Templates collection for related templates and variations.