Angular Material + FastAPI Log Analytics CLAUDE.md Template

Overview

The CLAUDE.md template is a copyable Claude Code blueprint for a complete Angular Material frontend paired with a FastAPI backend focused on log analytics. It defines project roles, architecture rules, a stack-specific file structure, authentication, database, validation, security, testing, deployment, and explicit do-not rules to keep Claude-generated code aligned with this stack.

Direct answer: This CLAUDE.md Template provides a ready-to-paste Claude Code instruction block for Angular Material + FastAPI log analytics, enabling rapid scaffolding and consistent practices.

When to Use This CLAUDE.md Template

• You're building a log analytics dashboard with an Angular Material frontend and a FastAPI backend.
• You want a repeatable CLAUDE.md blueprint to scaffold frontend/backend files, auth, DB, and tests.
• You require a production-oriented baseline including deployment steps and security guidance.
• You want a copyable Claude Code block you can paste into CLAUDE.md and adapt over time.

Copyable CLAUDE.md Template

# CLAUDE.md

Project role: You are a full-stack engineer for an Angular Material frontend and a FastAPI backend building a log analytics dashboard. Claude Code will generate scaffolds, endpoints, tests, and deployment guidance from this blueprint.

Architecture rules:
- Frontend (Angular Material) communicates with Backend (FastAPI) exclusively over HTTPS at /api endpoints.
- Backend exposes a minimal, well-documented REST API for logs and dashboards.
- Use PostgreSQL as the database; access via SQLAlchemy ORM; migrations via Alembic.
- Separate concerns: frontend app, backend API, and shared data models.

File structure rules:
- Place frontend under frontend/ and backend under backend/.
- Use conventional Angular project structure: frontend/src/app, frontend/src/styles, angular.json, package.json.
- Use FastAPI project structure: backend/app main.py, api/, models/, schemas/, core/, database/, tests/.
- Do not generate monolithic single-file solutions.

Authentication rules:
- Use OAuth2PasswordBearer with JWT tokens for backend authentication.
- Frontend stores tokens in memory; refresh tokens are rotated every 15 minutes; never store in localStorage without encryption.
- All protected endpoints require a valid access token.

Database rules:
- PostgreSQL database; connection via DATABASE_URL env var.
- Use SQLAlchemy models with Pydantic schemas for input/output.
- Enforce unique constraints relevant to logs, dashboards, and users.

Validation rules:
- Use Pydantic models for request validation and response serialization.
- Validate request payloads strictly; reject unknown fields unless explicitly allowed.
- Validate user input for log ingestion to prevent schema drift.

Security rules:
- Enforce HTTPS, CORS with tight origins, and no permissive wildcard GETs on sensitive endpoints.
- Sanitize inputs and forbid arbitrary code execution; avoid eval or exec at all times.
- Use rate limiting on ingestions and dashboards endpoints.
- Never log secrets or tokens.

Testing rules:
- Backend: pytest with fixtures for database, endpoints, and mock data.
- Frontend: Angular test suite with Jasmine/Karma; end-to-end tests with Playwright.
- Coverage targets: backend 85%, frontend 80%.

Deployment rules:
- Dockerize both frontend and backend; docker-compose for local dev.
- Use non-root users in containers; bind mounted volumes for db data.
- Use environment variables for secrets; avoid hard-coded credentials.
- Include health checks and concise logging in production.

Things Claude must not do:
- Do not bypass authentication or authorization.
- Do not expose secrets or admin endpoints publicly.
- Do not generate code that includes eval, shell injections, or unsafe SQL concatenation.
- Do not assume a particular cloud provider unless specified in the blueprint.

Recommended Project Structure

frontend/
  src/
    app/
      dashboards/
      components/
      services/
    assets/
  angular.json
  package.json
  tsconfig.json

backend/
  app/
    main.py
    api/
      logs.py
      dashboards.py
    models/
      user.py
      log_entry.py
    schemas/
      user.py
      log_entry.py
    core/
      config.py
      security.py
      dependencies.py
    database/
      session.py
  requirements.txt
  alembic/
  Dockerfile
  docker-compose.yml

Core Engineering Principles

• Single source of truth: separate frontend, backend, and shared models; avoid duplicating business logic.
• Type safety: use Pydantic for data validation; enforce strict typing in Python and TypeScript.
• Security by default: strong authentication, encrypted secrets, and minimal exposure.
• Observability: structured logging, metrics, and traceability across frontend and backend.
• Iterative delivery: small, testable changes with reproducible deployments.

Code Construction Rules

• Frontend: components must use Angular Material with accessible, responsive design; use material theming and components consistently.
• Backend: FastAPI endpoints must be async, with dependency injection for DB sessions and auth.
• Models: separate SQLAlchemy models and Pydantic schemas; avoid circular imports.
• Validation: strict input validation; use pydantic BaseModel with field validators for critical fields.
• Error handling: uniform error responses with status codes and error messages; do not leak stack traces in production.
• Testing: include unit tests for models and endpoints; integration tests for ingestion and dashboards endpoints.
• Logging: structured JSON logging; include request IDs and trace IDs in logs.
• Documentation: auto-generated OpenAPI for backend; UI inline docs in frontend where appropriate.
• Performance: paginate log queries; avoid heavy in-memory processing on large logs.
• Accessibility: ensure Angular Material components meet WCAG 2.1 AA at least.

Security and Production Rules

• Authentication: OAuth2 JWT with short-lived access and refresh tokens; verify scopes on protected routes.
• Authorization: Role-based access control for dashboards and data exposure.
• Secrets: use environment variables or secret managers; never commit secrets to source control.
• Networking: limit ports and expose only required endpoints; enable TLS in production.
• Data security: encrypt sensitive fields; ensure log data does not contain PII where not needed.
• Observability: centralized logging, metrics, tracing for API calls.
• Resilience: circuit breakers for external services; retry strategies with backoffs.
• Backups: regular database backups and tested restore procedures.

Testing Checklist

• Unit tests for models and utilities in both frontend and backend.
• Integration tests for log ingestion endpoints and dashboard data retrieval.
• End-to-end tests for authentication, data flow, and UI dashboards.
• CI pipeline verifies tests pass on each merge; security scans optional but recommended.
• Manual exploratory testing and regression checks before releases.

Common Mistakes to Avoid

• Introducing lax input validation that allows malformed logs or payloads.
• Overly broad CORS or open admin endpoints exposing sensitive data.
• Storing tokens in insecure storage on the frontend.
• Skipping migrations or directly modifying the production database without tests.
• Underestimating e2e tests; rely solely on unit tests.

FAQ

Q: What is this CLAUDE.md Template for Angular Material + FastAPI?

A: A copyable Claude Code blueprint to scaffold a log analytics UI with an Angular Material frontend and a FastAPI backend, including auth, DB, tests, and deployment guidance.

Q: What authentication does it assume?

A: OAuth2 with JWT access tokens and short-lived refresh tokens; protected endpoints require valid tokens.

Q: What database and ORM are recommended?

A: PostgreSQL with SQLAlchemy for models and Pydantic for schemas; Alembic for migrations.

Q: How do I run this locally?

A: Use docker-compose up to start frontend and backend; set DATABASE_URL and JWT_SECRET environment variables; then open the UI and verify API access.

Q: How do I deploy to production?

A: Build and push Docker images; deploy with Docker Compose or Kubernetes; enable TLS and rotate secrets; monitor logs and metrics.