CLAUDE.md Template for Angular Material + FastAPI + DodoPayments

Overview

Direct answer: This CLAUDE.md Template provides a complete starter for an Angular Material frontend, a FastAPI backend, and DodoPayments integration with explicit rules and a copyable CLAUDE.md block you can paste into Claude Code.

What is CLAUDE.md? It is a structured instruction document guiding Claude Code on how to implement a stack-specific starter with deterministic rules, file structure, security constraints, and testing requirements. This page tailors CLAUDE.md to the Angular Material + FastAPI + DodoPayments stack, so you can reproduce a consistent starter environment.

When to Use This CLAUDE.md Template

• When you need a reproducible full-stack starter for Angular Material frontend and FastAPI backend with DodoPayments.
• When you want explicit architecture, file structure, and security constraints to guide Claude Code in a project bootstrap.
• When you require a deterministic, testable blueprint that can be pasted into CLAUDE.md for future projects.

Copyable CLAUDE.md Template

# CLAUDE.md

Project role: You are Claude Code, a software engineer who implements a complete Angular Material frontend + FastAPI backend with DodoPayments integration using clear architecture and rules.

Architecture rules:
- Frontend must be Angular with Angular Material, using a component-driven approach and a shared UI library.
- Backend must be FastAPI with async endpoints, Pydantic models, and clean router structure.
- Payment integration must use DodoPayments tokens via server-to-server calls; never store raw card data in your DB.
- Use a single API contract via typed DTOs; maintain a strict API surface and forward-compatible responses.
- Secrets must never be printed or logged in Claude's output.

File structure rules:
- Create a distinct frontend/ and backend/ directory; keep shared/ for cross-cutting utilities and DTOs.
- Do not mix frontend and backend code in the same folder; use dedicated subfolders.
- All API endpoints must be versioned under /api/v1/.

Authentication rules:
- FastAPI: OAuth2 with PasswordBearer or OAuth2 Authorization Code with PKCE for SPA flows.
- Use JWTs with short expiry and refresh token rotation; store tokens securely (HttpOnly cookies preferred for web apps).
- Backend must validate access tokens on every protected route.

Database rules:
- Use PostgreSQL; store only non-sensitive data and DodoPayments payment_token references; do not store raw card numbers.
- Use Alembic for migrations and track schema changes.
- Use proper indexes on user_id and payment_token columns.

Validation rules:
- Use Pydantic for request/response models with strict types.
- Validate input formats (emails, UUIDs) and reject unknown fields.
- Normalize and sanitize strings before persisting.

Security rules:
- Enforce HTTPS in all environments; set secure cookies and HTTPOnly flags.
- Enable CORS with a strict allowlist or disable in production.
- Never log secrets; mask sensitive data in logs.

Testing rules:
- Unit tests for frontend components and backend utilities.
- Integration tests for critical endpoints (auth, payments).
- Use mocks for DodoPayments tokens in tests.

Deployment rules:
- Docker Compose for local development; multi-stage Dockerfile for frontend and backend.
- Environment variables for secrets; do not bake secrets into images.
- Run tests in CI before merge; fail builds on test failures.

Things Claude must not do:
- Do not bypass tests or skip linting.
- Do not log secrets or raw payment data.
- Do not modify deployment workflows without validation.

Recommended Project Structure

frontend/                    # Angular Material frontend
  angular.json
  package.json
  tsconfig.json
  src/
    app/
      core/
      features/
      shared/
    assets/
  README.md

backend/                     # FastAPI backend
  app/
    main.py
    api/
    models/
    schemas/
    services/
    core/
  requirements.txt
  Dockerfile
  alembic/
  tests/

shared/                      # Shared DTOs and utilities
  dto/
  helpers/

Core Engineering Principles

• Single source of truth for API contracts; all endpoints and DTOs must map 1:1 to the documented CLAUDE.md rules.
• Clear separation of concerns between frontend, backend, and payment integration.
• Deterministic behavior; Claude should reproduce the same file structure and outputs for the same input.
• Security by default; validate inputs, handle secrets securely, and minimize data exposure.
• Observability; add structured logs, tracing, and metrics for critical flows (auth, payments).
• Testability; design code with unit and integration tests that cover common paths and edge cases.

Code Construction Rules

• Frontend: Use Angular Material components with a feature module pattern; avoid global state hacks; use RxJS for async streams.
• Backend: Use FastAPI routers with dependency injection; Pydantic models for requests/responses; async DB calls with async drivers.
• Payment: Tokenize payments through DodoPayments; never store raw card data; verify tokens on server-side calls.
• API contracts: Maintain explicit schemas for requests and responses; deprecate endpoints with versioning; do not break existing contracts without notice.
• Validation: Enforce strict typing and validation in both frontend forms and backend DTOs; return helpful errors.
• Security: Use HTTPS, CSRF considerations for SPA, and secure cookie handling; limit CORS securely.
• Deployment: Use Docker multi-stage builds; avoid secrets in image layers; use environment-specific configs.
• Do not: Use insecure libraries, bypass tests, or disable linting in CI.

Security and Production Rules

• Enable HTTPS in all environments and set HSTS where possible.
• Use HttpOnly, Secure cookies for authentication tokens.
• Limit CORS to known origins; disallow wildcard origins in production.
• Mask and redact sensitive data in logs; never log full card numbers or tokens.
• Monitor and alert on payment failure rates and API error rates.

Testing Checklist

• Frontend unit tests for components and services; ensure access to material UI works as expected.
• Backend tests for auth flows, payment endpoints, and data validation.
• Integration tests to cover end-to-end paths from login to payment flow.
• Deployment smoke tests; verify environment variables are loaded and app starts up cleanly.

Common Mistakes to Avoid

• Ignoring token expiration and refresh token handling.
• Storing raw payment card data or insecure tokens in the database.
• Overly permissive CORS or insecure secret management in CI/CD.
• Skipping tests or running tests with production config in development.
• Merging breaking changes without updating CLAUDE.md contracts.

FAQ

Q: What stack is covered by this CLAUDE.md Template?

A: Angular Material for the frontend, FastAPI for the backend, and DodoPayments for payment integration.

Q: What should I paste into CLAUDE.md?

A: The copyable CLAUDE.md Template block included in the Copyable CLAUDE.md Template section.

Q: How are payments secured?

A: By using DodoPayments tokenization and not storing raw card data; tokens are used on the server.

Q: Where can I customize the file structure?

A: In the Recommended Project Structure section; adapt as needed while preserving contracts.

Q: How do I run tests?

A: Run frontend tests (ng test) and backend tests (pytest); CI should run these automatically.