Angular Material + FastAPI Order Management CLAUDE.md Template

Overview

This CLAUDE.md Template for Angular Material + FastAPI order management provides a complete, copyable Claude Code guide to scaffold a robust stack with frontend in Angular Material and backend in FastAPI. It includes explicit project roles, architecture rules, file structure, authentication, data validation, security, testing, deployment, and anti-patterns. This CLAUDE.md template is the exact guide you can paste into CLAUDE.md to start implementing a production-ready order-management app.

Direct answer: Use this CLAUDE.md template to rapidly bootstrap an Angular Material frontend and FastAPI backend for order management, with stack-specific rules and a concrete project structure.

When to Use This CLAUDE.md Template

• You are starting a new Angular Material + FastAPI order-management project and need a consistent starter.
• You are onboarding engineers and want a single source of truth for architecture, file layout, and rules.
• You want a copyable Claude Code block to feed directly into Claude Code for reproducible scaffolding.
• You want stack-specific guidance that avoids generic boilerplate and focuses on the Angular + FastAPI integration.

Copyable CLAUDE.md Template

# CLAUDE.md

Project role: You are a senior frontend (Angular Material) and backend (FastAPI) engineer building a robust order management system. Your task is to deliver a CLAUDE.md template that codifies architecture, folder structure, and Claude Code rules for this stack.

Architecture rules:
- Use clean architecture: separate frontend and backend layers; define clear interfaces between them.
- Backend should expose REST endpoints for orders, customers, and inventory; frontend communicates via typed HTTP clients.
- Data contracts must be defined with Pydantic (backend) and TypeScript interfaces (frontend).
- Centralized configuration per environment (dev, staging, prod).
- Logging and telemetry via structured logs; avoid console-only logs in production.

File structure rules:
- Frontend: frontend/ with src/app/, modules/, services/, models/; Backend: backend/ with app/, api/, core/, models/, schemas/; Shared components live under a shared/ module in the frontend and a common lib in the backend.
- All routes, services, and models must be located under their respective feature domains (e.g., orders).

Authentication rules:
- Backend uses OAuth2 with JWTs (Password flow for token issuance; refresh tokens with rotation).
- Secure cookies or localStorage only as appropriate; prefer HttpOnly cookies for refresh tokens.
- All protected endpoints require valid JWT via FastAPI's OAuth2 scheme.

Database rules:
- PostgreSQL with SQLAlchemy ORM on the backend; Alembic for migrations.
- Tables: users, roles, users_roles, orders, order_items, products, customers, inventory.
- Use foreign keys with ON DELETE CASCADE where appropriate; consider soft deletes for orders if required by business rules.

Validation rules:
- Backend: Pydantic models for request/response payloads; strict typing for all endpoints.
- Frontend: TypeScript interfaces and runtime validation where feasible; use zod or Joi-equivalents if desired.

Security rules:
- CSRF protection for the frontend if using cookies; enable CORS only for trusted origins.
- Validate all inputs; avoid reflective errors in error messages; sanitize outputs.
- Use HTTPS in production; rotate secrets; avoid hard-coded credentials.

Testing rules:
- Backend: unit tests for services and models; integration tests for API endpoints using FastAPI's TestClient.
- Frontend: unit tests for components/services; end-to-end tests as needed (Cypress or Playwright).
- Tests run in CI on PRs and merges.

Deployment rules:
- Dockerized frontend and backend; docker-compose for local development; Kubernetes manifests for production if applicable.
- Environment variables managed via secrets manager; do not bake secrets in images.
- Health checks and readiness probes in deployment configurations.

Things Claude must not do:
- Do not bypass authentication or authorization checks.
- Do not access production data without proper mocks or fixtures.
- Do not assume availability of external services without fallbacks.
- Do not generate or rely on insecure defaults (e.g., weak secrets, insecure endpoints).

Recommended Project Structure

frontend/
  src/
    app/
      modules/
        orders/
          components/
            order-list/
            order-detail/
          services/
          models/
        shared/
      app.module.ts
      main.ts
    assets/
  angular.json
  package.json
  tsconfig.json

backend/
  app/
    api/
      endpoints/
        orders.py
        customers.py
        inventory.py
    core/
      config.py
      security.py
    models/
      order.py
      customer.py
      product.py
    schemas/
      order_schema.py
      customer_schema.py
  main.py
  requirements.txt
  alembic/
  Dockerfile

Core Engineering Principles

• Explicit contracts between frontend and backend via typed data schemas.
• Single responsibility: one module handles one domain (orders, customers, inventory).
• Composition over inheritance; prefer interfaces and dependency injection where possible.
• Type-safety and rigorous validation at all boundaries (Pydantic on backend, TS types on frontend).
• Environment-driven configuration and observable, structured logging.

Code Construction Rules

• Frontend: use Angular Material components; create feature modules for orders with strict routing guards.
• Backend: FastAPI app with routers per domain; use Pydantic models for requests and responses; use SQLAlchemy ORM with Alembic migrations.
• Data contracts must be aligned across frontend and backend (TypeScript interfaces & Pydantic schemas).
• Use a dedicated API client service to centralize HTTP calls; handle retries and error mapping consistently.
• Do not bypass authentication; always validate JWT on protected endpoints.

Security and Production Rules

• Enable HTTPS; manage secrets via environment variables or a secrets manager.
• Implement CORS with a strict allowlist; enable CSRF protection for cookie-based sessions.
• Validate all inputs; never leak internal error details to clients; use generic error messages.
• Rotate tokens; implement token revocation strategy if feasible.
• Use server-side logging with correlation IDs for tracing requests across frontend and backend.

Testing Checklist

• Unit tests for backend services and models; unit tests for frontend components and services.
• Integration tests for FastAPI endpoints using TestClient; ensure 401/403 paths are covered.
• End-to-end tests for key flows (create order, update status, retrieve list) if budget allows.
• CI should run linting, type checks, and tests on every PR.

Common Mistakes to Avoid

• Assuming the frontend and backend share runtime code; keep contracts explicit and separate.
• Overfitting to a single database or ORM; plan migrations and data models with future growth in mind.
• Storing secrets in code or logging sensitive data.
• Ignoring accessibility in Angular Material components.

FAQ