Angular Material + FastAPI PayPal Payments CLAUDE.md Template

Overview

This CLAUDE.md Template documents a complete stack: Angular Material for the frontend and a FastAPI backend, integrated with PayPal Payments. It includes Claude Code instructions to guide you through architecture, file structure, authentication, data validation, security, testing, and deployment. It is crafted for developers who want a copyable starter that lands quickly in a real project.

Direct answer: It provides a ready-to-paste CLAUDE.md block plus explicit, stack-specific rules to implement PayPal payments with a clean Angular + FastAPI setup.

When to Use This CLAUDE.md Template

• Starting a new PayPal-enabled checkout flow with an Angular Material UI and a FastAPI backend.
• Standardizing code structure for frontend payments components and backend payment endpoints.
• Onboarding teammates with a proven blueprint for payments, security, and testing.
• Anchoring a repo with a copyable CLAUDE.md that reduces context-switching during implementation.

Copyable CLAUDE.md Template

# CLAUDE.md

Project role: Full-stack engineer responsible for implementing a PayPal checkout flow using Angular Material on the frontend and FastAPI on the backend. Claude Code acts as the integration guide and policy enforcer.

Architecture rules:
- Frontend: Angular + Angular Material, TypeScript, RxJS; uses PayPal JS Checkout for client-side order creation.
- Backend: FastAPI, Python 3.11+, Pydantic models, SQLAlchemy with PostgreSQL for orders and payments; endpoints for create-order, capture-payment, and webhook handling.
- Communication: RESTful API with JWT-based authentication; backend validates PayPal webhook signatures and idempotency for order captures.
- Secrets: All PayPal credentials and secrets stored in environment variables; no hard-coded values in code or CLAUDE.md.
- Observability: Centralized logging (JSON), structured traces, and basic metrics for health and payment events.

File structure rules:
- Frontend and backend live in separate dirs under a monorepo layout.
- Public API surface surface is in /backend/app/routers/payments and /frontend/src/app/payments/paypal.
- All sensitive keys and secrets are read from env vars (.env in dev) and not checked into source control.
- Tests live under /tests with distinct unit and integration tests for payments.

Authentication rules:
- Use OAuth2 / JWT for API access; Backend issues access tokens for clients; Refresh tokens rotated every 24 hours.
- Endpoints: /api/payments/create-order, /api/payments/capture, /api/payments/webhook; Token required for /create-order and /capture as per policy.

Database rules:
- PostgreSQL store: users, payments, orders; Use decimal for monetary amounts; Payment status fields (CREATED, APPROVED, CAPTURED, CANCELLED).
- Use SQLAlchemy models with Alembic migrations; enforce foreign keys and timestamps.

Validation rules:
- Pydantic models validate all inputs; amount & currency validate to USD and positive values; PayPal order IDs validated by length and format.
- Server responses always include status, id, and error field if applicable.

Security rules:
- Do not expose PayPal client secret in frontend code; use server-side lookups; validate webhook payloads with PayPal's signatures.
- Enforce TLS, CSRF considerations for SPA; CORS restricted to allowed origins.
- Do not ship literal secrets or keys in CLAUDE.md or repo; rotate credentials periodically.

Testing rules:
- Unit tests for data models and payment endpoints (pytest); integration tests with PayPal sandbox; end-to-end tests using a mocked PayPal flow.
- Use httpx for HTTP tests; mock webhook events; verify idempotent capture behavior.

Deployment rules:
- Dockerized frontend (NGINX + static assets) and backend (FastAPI) with a shared network; docker-compose for local dev and a production Kubernetes manifest for deployment.
- Secrets injected via environment variables; PayPal sandbox credentials during dev and production keys in prod.
- CI should run linting, tests, and type checks on push.

Things Claude must not do:
- Do not call PayPal APIs from frontend code or bypass server-side validation.
- Do not hardcode credentials or tokens in code or CLAUDE.md blocks.
- Do not bypass authentication or expose admin endpoints to unauthenticated users.
- Do not ignore PayPal webhook signature validation or idempotency checks.

Recommended Project Structure

project-root/
├── frontend/
│   ├── src/
│   │   ├── app/
│   │   │   └── payments/
│   │   │       └── paypal/
│   │   │           ├── components/
│   │   │           │   ├── paypal-checkout.component.ts
│   │   │           │   └── ...
│   │   │           └── services/
│   │   │               └── paypal.service.ts
│   │   └── index.html
│   └── angular.json
├── backend/
│   ├── app/
│   │   ├── main.py
│   │   ├── routers/
│   │   │   └── payments/
│   │   │       └── paypal.py
│   │   ├── models/
│   │   │   └── payment.py
│   │   └── schemas/
│   │       └── payment.py
│   └── requirements.txt
├── infra/
│   ├── docker-compose.yml
│   └── k8s/
└── tests/
    ├── unit/
    ├── integration/
    └── e2e/

Core Engineering Principles

• Single responsibility and clear boundaries between frontend, backend, and payments logic.
• Explicit contracts via typed models (TypeScript for frontend, Pydantic for backend).
• Defensive programming with validation, error handling, and idempotency for payments.
• Security by design: secrets management, webhook validation, TLS, and least-privilege access.
• Test first: comprehensive unit and integration tests for payment flow.
• Observability: structured logs, tracing, and metrics around payment events.

Code Construction Rules

• Frontend: Use Angular Material components for checkout UI; keep components small and testable; use OnPush change detection; strict typing.
• Backend: FastAPI with Python 3.11; Pydantic models for requests/responses; SQLAlchemy ORM with PostgreSQL; migrations via Alembic.
• PayPal integration: use PayPal Checkout JS on the frontend for order creation, and server-side capture via FastAPI endpoints; sandbox first in dev.
• Environment management: keep PayPal client IDs, secrets, and webhook signatures in env vars; never commit to VCS.
• Validation: robust input validation for payments; validate currency and amount; verify webhook signatures.
• Security: restrict CORS, enforce TLS, and validate all incoming webhook data; implement rate limiting for endpoints.
• Code quality: linting, type checking, and code reviews; use Black/isort for Python and ESLint for TS.
• Deployment: containerized services with environment-specific configs; use feature flags for payment mode (sandbox vs live).
• Do not: hardcode secrets, call PayPal from the frontend, skip webhook verification, or bypass authentication checks.

Security and Production Rules

• Store PayPal credentials in environment variables; rotate them regularly; never commit to repo.
• Validate PayPal webhooks using PayPal's signature verification; reject invalid payloads.
• Use TLS end-to-end; secure cookies and tokens; implement CORS with a strict allowlist.
• Never expose admin endpoints without proper authentication and authorization checks.
• Log sensitive events with redaction and keep an audit trail for payments.

Testing Checklist

• Unit tests for frontend components and backend models.
• Integration tests for payment endpoints: create-order, capture, and webhook flow with sandbox credentials.
• End-to-end tests for the user payoff journey using a mocked PayPal sandbox.
• Security tests: webhook validation, token verification, and input validation tests.
• Deploy tests: build and run in a staging environment with Docker Compose or a Kubernetes manifest.

Common Mistakes to Avoid

• Hardcoding PayPal credentials or client IDs in code or CLAUDE.md blocks.
• Exposing OAuth tokens or performing privileged actions from the frontend.
• Skipping webhook validation or relying on insecure webhook transports.
• Ignoring idempotency in capture flows, which can duplicate charges.
• Overexposing CORS or ignoring TLS in development vs production.

FAQ

• What is included in this CLAUDE.md Template? It provides a copyable CLAUDE.md block and stack-specific rules for Angular Material + FastAPI PayPal payments.
• Which stack prerequisites should I have? Angular Material setup, FastAPI backend, PostgreSQL, PayPal Sandbox credentials, and Claude Code access.
• How are payments secured in this template? Webhook validation, server-side capture, TLS, token-based auth, and secret management via environment vars.
• Where are the secret keys stored? In environment variables or secret management services; never in code or CLAUDE.md blocks.
• How do I test the PayPal integration? Use the PayPal Sandbox, write unit tests for API endpoints, and run end-to-end tests against a mocked flow.

Notes

Use this template to generate a CLAUDE.md file that your Claude Code instance can consume directly. It focuses on a concrete Angular Material + FastAPI PayPal Payments pattern and provides concrete rules to avoid architecture drift.