CLAUDE.md template for Angular Material + FastAPI Billing Portal | CLAUDE.md Template

Overview

CLAUDE.md template is a copyable Claude Code instruction set designed to guide Claude in building a billing portal using Angular Material for the frontend and FastAPI for the backend. It defines project roles, architecture, file structure, authentication, validation, security, testing, deployment, and what Claude must not do. This CLAUDE.md template page targets a specific stack: Angular Material + FastAPI Billing Portal.

Direct answer: Use the included CLAUDE.md template to generate Claude Code for this stack with precise constraints and executable rules.

When to Use This CLAUDE.md Template

• Building a billing portal with a polished Angular Material UI and a FastAPI backend.
• Defining strict contracts between frontend and backend via typed schemas.
• Documenting architecture and deployment rules for Claude Code to follow.
• Setting security, authentication, and data validation rules in a reproducible template.

Copyable CLAUDE.md Template

# CLAUDE.md
Project role: You are Claude, a code-focused assistant that generates Claude Code for an Angular Material + FastAPI Billing Portal stack. You write precise, executable instruction blocks for Claude Code. Do not produce proposals or non-executable prose.

Architecture rules:
- The frontend is an Angular Material SPA consuming a REST/JSON API from a FastAPI backend.
- The API layer must expose endpoints for auth, users, customers, invoices, payments, and billing plans.
- All data models and API contracts are defined using strict, typed schemas (TypeScript interfaces for frontend, Pydantic models for FastAPI).
- Use a layered architecture: frontend UI, API gateway, business logic, data access.
- Use JWT-based authentication with access and refresh tokens; attach tokens via Authorization: Bearer  header.
- Do not bypass authentication for any paid or sensitive endpoints.
- Use environment-based configuration; avoid hard-coded secrets.

File structure rules:
- Root/
  frontend/        # Angular Material app
  backend/         # FastAPI app
  docker-compose.yml
- Frontend structure
  frontend/src/app/
  frontend/src/environments/
  frontend/angular.json
  frontend/package.json
- Backend structure
  backend/app/
  backend/app/api/
  backend/app/core/
  backend/app/models/
  backend/app/schemas/
  backend/app/db/
- Do not create unrelated folders or files.

Authentication rules:
- Use JWT in HTTP Authorization header.
- Implement /auth/login (POST) to issue access token, /auth/refresh (POST) to refresh, and protect protected routes with dependency checks.
- Use HTTP 401 for unauthorized access.
- Do not hardcode user credentials.

Database rules:
- Use PostgreSQL with a separate schema billing.
- Use encrypted password storage (bcrypt) for user credentials.
- Do not store full card data; use tokenization with a payment provider via backend.

Validation rules:
- Validate all inputs via Pydantic models in FastAPI and via TypeScript types in the frontend.
- Return 422 for validation errors; provide precise error messages.

Security rules:
- Do not log secrets; mask sensitive fields in logs.
- Enforce TLS in production; allow CORS only for the frontend domain.
- Secure cookies with HttpOnly and Secure flags for session tokens.

Testing rules:
- Backend: unit tests with pytest for models and endpoints; integration tests for auth and billing endpoints.
- Frontend: unit tests for components/services; end-to-end tests for auth flow using a headless browser.

Deployment rules:
- Dockerize frontend with nginx or a static build; FastAPI as Gunicorn/Uvicorn behind a reverse proxy.
- Use docker-compose for local dev; provide environment variables in .env.example.
- Deploy to a cloud provider with separate staging/production configs.

Things Claude must not do:
- Do not generate code that bypasses authentication.
- Do not embed secrets or plaintext passwords.
- Do not emit cardholder data or PCI-sensitive info in logs or responses.
- Do not propose using deprecated APIs or libraries.
- Do not produce non-reproducible architecture drift.

Recommended Project Structure

angular-material-fastapi-billing-portal/
├── frontend/
│   ├── src/
│   │   ├── app/
│   │   │   ├── components/
│   │   │   ├── services/
│   │   │   └── pages/
│   │   ├── assets/
│   │   └── index.html
│   ├── angular.json
│   └── package.json
├── backend/
│   ├── app/
│   │   ├── api/
│   │   ├── core/
│   │   ├── models/
│   │   ├── schemas/
│   │   └── main.py
│   ├── requirements.txt
│   └── Alembic.ini
├── docker-compose.yml

Core Engineering Principles

• Contract-first development: define clear API contracts and UI interfaces before implementation.
• Security-by-default: authenticate all sensitive operations; never trust client input.
• Strong typing across stack: Pydantic models on the backend and TypeScript interfaces on the frontend.
• Observability: structured logging, metrics, and tracing for all services.
• Component-driven UI: reuse Angular Material components and follow OnPush change detection.

Code Construction Rules

• Frontend must use Angular Material components for UI, accessible ARIA labels, and responsive design.
• Backend must use FastAPI routers, Pydantic models, and dependency injection; avoid global state.
• All API responses must be typed; use proper HTTP status codes for error handling.
• Validation errors must return 422 with field-level messages.
• Authentication must implement JWT with access/refresh tokens; store only non-sensitive data in cookies if used.
• Do not bypass authentication checks on any endpoint that handles billing data.
• Secrets must be sourced from environment variables; avoid hard-coded values.
• Logging must mask secrets and avoid including card data in logs.

Security and Production Rules

• Enable TLS in production and enforce HTTPS-only communications.
• Configure CORS to allow only the billing portal domain.
• Do not log or expose PII or payment card data; use tokenization for payments.
• Implement rate limiting on sensitive endpoints; protect against brute force login attempts.
• Regularly rotate signing keys and use short-lived access tokens with refresh tokens.

Testing Checklist

• Backend unit tests for models, validators, and endpoints.
• Integration tests for auth flows (login, refresh) and CRUD for billing entities.
• Frontend unit tests for UI components and services; end-to-end tests for login and checkout flows.
• Deployment smoke tests to verify containerized services start correctly.

Common Mistakes to Avoid

• Over-abstracting business logic into the frontend; keep business rules on the backend.
• Storing raw card data or credentials in logs or memory.
• Ignoring type validation on both client and server sides.
• Relaxing authentication on admin or billing endpoints.
• Rolling custom auth without thorough security considerations.

FAQ

What is a CLAUDE.md template?

A copyable Claude Code starter that encodes stack-specific rules for Claude to follow during development.

Which stack does this template cover?

Angular Material frontend with a FastAPI backend for a billing portal.

Can Claude modify deployment details?

Yes, within the Deployment rules; avoid non-reproducible drift.

How do I customize for different environments?

Environment-specific rules and tokens should be parameterized in the template.

What should I do if I see a security concern?

Flag it in the Claude Code block and adjust the template to enforce the fix.