Angular Material + FastAPI Kafka CLAUDE.md Template

Overview

The CLAUDE.md template documents a production-ready Angular Material frontend paired with a FastAPI backend and Kafka messaging. This page provides a copyable CLAUDE.md template block you can paste into your repository to bootstrap Claude Code guidance for the stack.

Direct answer: This CLAUDE.md Template offers concrete, copy-pasteable Claude Code instructions that enforce a disciplined frontend-backend-messaging contract using Angular Material, FastAPI, and Kafka.

When to Use This CLAUDE.md Template

• You are starting an Angular Material UI project with a FastAPI API and Kafka-based event streaming.
• You need a reproducible Claude Code starter for a team adopting an event-driven architecture.
• You want a documented architecture, file structure, and security practices for this stack.
• You require a concrete project skeleton to onboard developers quickly.

Copyable CLAUDE.md Template

# CLAUDE.md

Project role: You are Claude, an AI assistant that writes practical, production-ready code and guidelines for the Angular Material + FastAPI + Kafka stack. You will generate code, file structures, and rules in a copyable CLAUDE.md format.

Architecture rules:
- Maintain a strict frontend/backend/messaging boundary. The frontend (Angular Material) consumes REST/WS from FastAPI; all domain events flow through Kafka topics. Do not access the DB directly from the frontend.
- Containerize services with Docker; use docker-compose for local development and separate envs for dev/stage/prod.
- Define explicit data contracts for API requests/responses and Kafka messages; mirror models across services where needed.

File structure rules:
- Frontend: frontend/angular-app with Angular Material components.
- Backend: backend/fastapi-app with routers, Pydantic models, and SQLAlchemy models.
- Messaging/config: infra/kafka with topic names, ACLs, and example consumers/producers.
- Use a single docker-compose.yml to wire services.

Authentication rules:
- SPA uses OAuth2 with PKCE; API endpoints validate JWT access tokens.
- Secrets are provided via environment variables or a secret manager; never hard-coded.

Database rules:
- PostgreSQL with SQLAlchemy; migrations via Alembic; protect credentials and use separate read/write DBs if needed.

Validation rules:
- Pydantic models for FastAPI; TypeScript types for Angular; runtime validation on both sides.

Security rules:
- Enforce TLS for all services; tighten CORS to the frontend domain; sanitize all inputs; avoid leaking secrets.

Testing rules:
- Backend: pytest with httpx for API tests; unit and integration tests for models/routers.
- Frontend: Jasmine/Karma tests; TypeScript linting and type checks.

Deployment rules:
- Docker Compose for local dev; Kubernetes manifests for prod if required; CI/CD pushes container images with proper tags.

Things Claude must not do:
- Do not embed plaintext secrets in code or configuration.
- Do not bypass authentication or authorization checks.
- Do not generate code that uses deprecated dependencies without migration plans.

Recommended Project Structure

frontend/
  angular-app/
    src/
    angular.json
    package.json
backend/
  fastapi-app/
    main.py
    app/
      api/
      core/
      models/
      schemas/
    requirements.txt
    Dockerfile
infra/
  kafka/
    server.properties
  docker-compose.yml

Core Engineering Principles

• Explicit contracts between frontend and backend; clear API and message schemas.
• Idempotent Kafka consumers and idempotent message handling.
• Observability: structured logging, metrics, and tracing for all services.
• Security by default: least privilege, encrypted communication, secret management.
• Reproducible builds and deployments with IaC and versioned configs.
• Type safety across TypeScript (frontend) and Pydantic models (backend).
• Automated tests covering unit, integration, and end-to-end flows.

Code Construction Rules

• Frontend: enable strict mode, TypeScript types, strictNullChecks, and Angular Material theming.
• Backend: FastAPI with Pydantic models, async endpoints, and SQLAlchemy with Alembic migrations.
• Kafka: define topics with schemas; producers/consumers validate payloads against shared contracts.
• Use environment-based configuration and secret management; avoid hard-coded secrets.
• Validation: all inputs validated; sanitize outputs; consistent error handling.
• Dependency management: pin versions; use lockfiles; minimal surface area in dependencies.
• Do not bypass authentication or expose admin endpoints publicly.

Security and Production Rules

• Use TLS everywhere; enable TLS for FastAPI via uvicorn with SSL, and for Kafka with SASL_SSL.
• CORS configured to the frontend domain only; secrets never exposed in code.
• Audit logs and metrics exposed to a secure monitoring stack.
• Regular dependency audits and vulnerability scanning in CI.
• Backups for PostgreSQL; disaster recovery planning in place.

Testing Checklist

• Backend: pytest with httpx; test suites for models, endpoints, and Kafka integration mocks.
• Frontend: unit tests for components/services; end-to-end tests via Cypress or similar if used; linting enforced.
• Deployment tests: smoke tests after deployment; health checks for API and Kafka brokers.

Common Mistakes to Avoid

• Assuming frontend can directly access the database or Kafka without proper APIs.
• Overcomplicating the Kafka topology; under-provisioning topics and ACLs.
• Skipping type validation on API and message payloads.
• Ignoring security hardening in development environments.

FAQ

What is this CLAUDE.md Template for?

This page provides a copyable CLAUDE.md template for a stack combining Angular Material, FastAPI, and Kafka to seed Claude Code instructions.

Which stack does this template cover?

Angular Material frontend, FastAPI backend, and Kafka-based messaging.

How do I use the CLAUDE.md block?

Copy the block into your repository's CLAUDE.md file and customize paths and settings for your environment.

What are the security guidelines?

Use TLS, restrict CORS, avoid embedding secrets, and enforce token-based authentication for API access.

What is included in the project structure?

A frontend Angular Material app, a FastAPI backend, and Kafka/infrastructure configuration with docker-compose wiring.