Angular Material + FastAPI Stripe Payments CLAUDE.md Template

Overview

A CLAUDE.md template for Angular Material + FastAPI Stripe Payments. This page provides a copyable CLAUDE.md template block and a stack-specific project blueprint to bootstrap a production-ready payment flow using Angular Material on the frontend and FastAPI on the backend with Stripe.

When to Use This CLAUDE.md Template

Use this template when you need a consistent, production-ready starting point for a Stripe-based checkout with a modern Angular UI and a FastAPI API. It ensures clear separation of concerns, strong typing, and testability. It is designed for Claude Code to generate code scaffolds and guide your implementation.

• When building a Stripe-powered checkout flow with Angular Material UI and a FastAPI backend.
• When you want a copyable CLAUDE.md template to guide code generation and maintain consistency across teams.
• When you need a production-ready structure with tests, CI-friendly rules, and Docker deployment guidance.

Copyable CLAUDE.md Template

# CLAUDE.md
Project role: You are Claude Code. Your task is to generate a complete Angular Material + FastAPI Stripe Payments starter project with a clean frontend/backend separation, Stripe integration using PaymentIntents, and a webhook for payment confirmations. The code must be production-friendly and ready for CI/CD.

Architecture rules:
- Frontend: Angular (v15+) using Angular Material; a dedicated payments feature module; communicate with backend via REST at /api/v1/payments; no business logic in components; use services to encapsulate API calls.
- Backend: FastAPI app; modular routers; Stripe Python library for payments; webhook endpoint at /webhook; environment-configured credentials; rely on pydantic models for validation.
- Data flow: frontend requests create PaymentIntent via backend; backend returns clientSecret to frontend; frontend completes payment using Stripe.js; backend confirms via webhook.

File structure rules:
- Do not merge frontend and backend under a single root; keep two top-level dirs: frontend/ and backend/
- Each side has its own README, tests, and CI config.
- Frontend uses src/app/features/payments/ with components and services; backend uses app/api/v1/payments.py and app/models/.

Authentication rules:
- Backend endpoints protected with JWT-based authentication (OAuth2PasswordBearer); include get_current_user dependency; token is acquired from /auth/token (mock for template).
- Webhook endpoint allows Stripe to post events; verify signature using Stripe library.

Database rules:
- PostgreSQL via SQLAlchemy; models for User and Payment; Alembic migrations recommended.
- Payment records include id, amount, currency, status, payment_intent_id, customer_id, created_at.

Validation rules:
- Pydantic models for request/response; amount > 0; currency in ISO codes; payment_intent uses Stripe.

Security rules:
- Do not hardcode secret keys; load from environment variables; verify Stripe webhook signatures; CSRF safe for API; avoid exposing secret keys to frontend.

Testing rules:
- Backend: pytest unit tests for endpoints and models; Stripe webhook tests with mock events; frontend: basic unit tests for components/services.
- Use deterministic test data; mock Stripe where possible.

Deployment rules:
- Dockerfile for backend (uvicorn) and frontend (ng build); docker-compose to run both; environment variables: STRIPE_API_KEY, STRIPE_WEBHOOK_SECRET, DATABASE_URL.
- Use HTTPS in production; CI should run tests and linting.

Things Claude must not do:
- Do not embed real secret keys in code.
- Do not generate frontend logic that exposes Stripe secret keys.
- Do not bypass webhook signature verification.
- Do not assume deployment specifics beyond a standard containerized setup.

Recommended Project Structure

frontend/
  src/
    app/
      core/
      features/
        payments/
          components/
          services/
      app.module.ts
      app-routing.module.ts
  angular.json
  package.json
  tsconfig.json
backend/
  app/
    main.py
    api/
      v1/
        payments.py
    models/
      user.py
      payment.py
    core/
      config.py
  requirements.txt
  Dockerfile
  docker-compose.yml

Core Engineering Principles

• Clear separation of frontend and backend concerns.
• Strong typing with TypeScript on the frontend and Pydantic models on the backend.
• Idempotent API design and deterministic data schemas.
• Explicit validation, error handling, and observable logging.
• Secure handling of payment data and secrets; do not leak keys to the client.

Code Construction Rules

• Frontend must use Angular Material components (MatCard, MatFormField, MatInput, MatButton) for the checkout UI.
• Backend must expose a /api/v1/payments/create-payment-intent endpoint that returns { clientSecret, paymentIntentId }.
• Use Stripe PaymentIntent with automatic_capture; handle currency and amount validation server-side.
• Store minimal payment metadata in PostgreSQL; avoid storing sensitive card data beyond Stripe payment_id.
• Keep business logic in services and routers, not in components or route handlers.
• Do not use client-secret keys in the frontend; always fetch clientSecret from backend.
• Ensure proper error handling and standardized error responses.

Security and Production Rules

• Load all secrets from environment variables; never commit secrets.
• Verify Stripe webhook signatures using the Stripe library and the secret configured in env vars.
• Use HTTPS; enable CORS only for safe origins if needed.
• Rotate API keys periodically and maintain versioned API contracts.
• Audit logs for payment events; redact sensitive data in logs.

Testing Checklist

• Unit tests for backend: validation, error paths, and Stripe interaction with mocks.
• Integration tests for /api/v1/payments endpoints and webhook processing.
• Frontend tests for the payments component and service layer; smoke tests for UI rendering.
• CI: run lint, tests, and type checking on commit.

Common Mistakes to Avoid

• Exposing Stripe secret keys in frontend code or public repos.
• Assuming Stripe test keys work in production without proper config.
• Skipping webhook signature verification leading to spoofed events.
• Mixing business logic with UI code; ignoring separations of concerns.

FAQ

What is this CLAUDE.md Template for?

It provides a ready-to-use CLAUDE.md template for an Angular Material frontend + FastAPI Stripe backend starter with clear rules for Claude Code to generate code scaffolds.

Which stack does this template target?

Angular Material on the frontend, FastAPI on the backend, with Stripe Payments integration.

How do I use the copyable CLAUDE.md block?

Paste the block into a CLAUDE.md file and run Claude Code to generate or scaffold the project as described.

What security considerations are included?

Stripe webhook verification, environment-based secrets, no client-secret exposure, and proper authentication for API endpoints.

Where can I deploy this template?

As a dockerized stack; use docker-compose for frontend and backend, deploy to a cloud host with HTTPS termination.