Angular Material + FastAPI Usage Based Billing CLAUDE.md Template (CLAUDE.md template)

Overview

The CLAUDE.md template is a copyable Claude Code starter designed for developers building an Angular Material frontend with a FastAPI backend that implements usage-based billing. It provides a ready-to-paste CLAUDE.md code block and stack-specific guidance for project structure, authentication, validation, and deployment. Direct answer: paste the code block into your CLAUDE.md to bootstrap a usage-based billing workflow for this stack.

When to Use This CLAUDE.md Template

• You are building an Angular Material SPA that communicates with a FastAPI backend.
• You need a clear CLAUDE.md template to standardize usage-based billing logic (metering, pricing tiers, invoices).
• You want a copyable Claude Code block that developers can paste to scaffold architecture, tests, and deployment rules.

Copyable CLAUDE.md Template

# CLAUDE.md

Role: Platform Engineer for Angular Material + FastAPI Usage-Based Billing
Architecture:
  Frontend: Angular Material SPA
  Backend: FastAPI, PostgreSQL, Stripe-like billing adapter
  Deployment: Docker Compose

File structure rules:
  - frontend/
  - backend/
  - docker-compose.yml
  - .env.example

Authentication rules:
  - Use OAuth2 with JWT Bearer tokens
  - Access token short-lived; refresh token rotation

Database rules:
  - PostgreSQL with tables: users, api_keys, subscriptions, usage_logs, invoices
  - Enforce foreign keys and indices on user_id, timestamp

Validation rules:
  - Backend: Pydantic models for requests and responses
  - Frontend: strong TypeScript types and Reactive Forms validation

Security rules:
  - Passwords hashed with bcrypt
  - Secrets injected via environment variables, not in code
  - Enforce HTTPS in production; CORS configured for the frontend domain

Testing rules:
  - Backend: unit tests for models and endpoints; integration tests for billing workflow
  - Frontend: unit tests for components/services; end-to-end tests for billing UI

Deployment rules:
  - Docker Compose with frontend, backend, Postgres, and (optionally) a mock payment service
  - Environment variables: SECRET_KEY, DATABASE_URL, STRIPE_API_KEY
  - Run migrations on startup; seed initial data for dev

Do not do:
  - Do not bypass authentication checks
  - Do not expose secret keys in logs or code
  - Do not hard-code billing amounts or test keys

Recommended Project Structure

project-root/
  frontend/
    src/
      app/
        components/
        services/
        models/
        app.module.ts
      assets/
    angular.json
    package.json
    tsconfig.json
  backend/
    app/
      api/
        v1/
          endpoints.py
      core/
      models/
      schemas/
      services/
      main.py
    tests/
    requirements.txt
    alembic.ini
  docker-compose.yml

Core Engineering Principles

• Explicit contracts between frontend and backend using clear input/output models
• Secure by default: sane defaults, least privilege, and secret management
• Observability: structured logs, metrics, and tracing for the billing path
• Test-driven-like guidance: specify tests for critical paths in both layers
• Incremental deployability: containerized services with clear migration steps

Code Construction Rules

• Frontend: use Angular Material components and reactive forms; strongly type all API payloads
• Backend: FastAPI with Pydantic models for request validation; path operations lean and well-documented
• Billing: separate service/interface for meter data, pricing tiers, and invoice generation
• Environment: do not hard-code secrets; pull from environment or secret manager
• Validation: validate all user inputs; guard against overflows and negative meters
• Security: rotate JWTs; store password hashes; implement rate limiting on sensitive endpoints
• Deployment: use Docker Compose for local dev and production-like environments
• Do not do: rely on client-side validation alone; never trust client input

Security and Production Rules

• Use HTTPS; configure TLS in production deployments
• JWTs with short lifetimes and refresh tokens; store tokens securely
• Secrets managed via environment variables or secret management tools; never commit to repo
• Billing data must be encrypted at rest; protect PCI-relevant data if applicable
• Audit logging for billing events; protect logs from tampering
• Regular dependency vetting and vulnerability scanning in CI

Testing Checklist

• Unit tests for Pydantic models and FastAPI routers
• Integration tests for the billing flow: meter event, price calculation, invoice creation
• Frontend tests: component and service tests for billing UI; end-to-end flows for payments
• Deployment tests: smoke tests after docker-compose up

Common Mistakes to Avoid

• Embedding secrets in code or logs
• Assuming frontend validation is sufficient for security
• Overly permissive CORS in production
• Ignoring migration scripts and backward-compatibility in billing models

FAQ

What is this CLAUDE.md Template for?

It provides a complete, copyable CLAUDE.md template for a stack using Angular Material and FastAPI with usage-based billing.

Which stack does it cover?

Angular Material frontend paired with a FastAPI backend and a PostgreSQL database for usage-based billing.

How do I customize for my project?

Modify the architecture and file structure sections in the CLAUDE.md block to reflect your services, endpoints, and billing model.

Where do I paste the CLAUDE.md code?

In the root CLAUDE.md of your project or in your CLAUDE.md templates repository to standardize onboarding.

What are deployment steps?

Use the Docker Compose example to run frontend, backend, and database; configure environment variables for secrets and keys.