Angular Material + FastAPI Invoice Management CLAUDE.md Template

Overview

CLAUDE.md template for Angular Material + FastAPI Invoice Management provides a copyable Claude Code starter. It defines the stack focus, project scope, and the required structure for engineers to bootstrap an invoice management app with a polished Angular frontend using Material components and a FastAPI backend with robust validation and security.

Direct answer: Use this template to generate a complete CLAUDE.md block that details architecture, rules, and deployment for the stack.

When to Use This CLAUDE.md Template

• Kick off a new Angular Material + FastAPI invoice project with a consistent CLAUDE.md block
• Ensure architecture rules and file structure are documented for new contributors
• Enforce authentication, validation, and security rules from the start
• Provide a shareable Claude Code block for onboarding and audits

Copyable CLAUDE.md Template

# CLAUDE.md
Project role: You are Claude Code guiding the Angular Material + FastAPI invoice management project. Produce precise Claude Code blocks for this stack.
Architecture rules:
  - Backend uses FastAPI with Pydantic models for invoices, customers, items
  - Frontend uses Angular with Angular Material components
  - API contracts follow OpenAPI v3 and strict typing
File structure rules:
  - frontend contains src app with invoice module
  - backend contains app api v1 with invoices, customers, items
  - shared contains common models and utils
Authentication rules:
  - Use OAuth2 with JWT tokens
  - Tokens stored in HttpOnly cookies
Database rules:
  - PostgreSQL with async support
  - Use SQLAlchemy or Tortoise ORM with migrations
Validation rules:
  - Validate all inputs with Pydantic
  - Enforce business rules for invoices total and status
Security rules:
  - All endpoints require authentication
  - Enable HTTPS and strict CORS
  - Never log tokens or secrets
Testing rules:
  - Unit tests for models and services
  - Integration tests for invoices API and frontend API calls
Deployment rules:
  - Local dev uses docker compose
  - Prod uses Kubernetes or cloud run with CI/CD
Things Claude must not do:
  - Do not expose secrets
  - Do not generate insecure code
  - Do not bypass authentication

Recommended Project Structure

frontend/
  src/
    app/
      invoice/
        components/
        services/
        models/
  angular.json
  package.json
backend/
  app/
    main.py
    api/
      v1/
        invoices.py
        customers.py
  requirements.txt
  alembic/
    env.py

Core Engineering Principles

• Use explicit contracts between frontend and backend
• Keep frontend and backend concerns separate
• Prefer typed data exchanges via Pydantic and TypeScript interfaces
• Write idempotent endpoints for create/update/delete flows
• Security by default, least privilege, and secure storage
• Automated tests and reliable CI/CD

Code Construction Rules

• Backend models defined with Pydantic and validated by FastAPI
• Endpoints validate inputs and return strict response shapes
• Frontend uses Angular services to call API with proper error handling
• Environment configuration for dev, staging, prod
• Do not hardcode secrets in code or CLAUDE.md blocks
• Do not bypass authentication or authorization checks

Security and Production Rules

• Enable HTTPS everywhere and strict CORS origins
• Store access tokens in HttpOnly cookies; avoid localStorage for tokens
• Use PostgreSQL with encryption at rest and role based access
• Rotate secrets and use a secrets manager in prod
• Audit logs and monitor endpoints for anomalies

Testing Checklist

• Unit tests for Pydantic models and services
• Integration tests for invoice APIs and auth flows
• End to end tests for invoice creation and payment flows
• Security tests including OAuth2 token validation and CSRF considerations
• CI/CD runs unit, integration and linting checks

Common Mistakes to Avoid

• Using localStorage for tokens in SPA with JWT
• Skipping input validation and trusting client side only
• Ignoring migrations and schema drift
• Overcomplicating the architecture without clear boundaries

FAQ