CLAUDE.md Template: Angular Material + FastAPI Subscription SaaS Starter

Overview

This CLAUDE.md template explains how to scaffold a production-ready Subscription SaaS using Angular Material for the frontend and FastAPI for the backend. It provides Claude Code instructions to ensure consistent architecture, tooling, and deployment with Stripe-based subscriptions and PostgreSQL storage.

When to Use This CLAUDE.md Template

• You want a copyable CLAUDE.md template for Angular Material + FastAPI stack aimed at subscription-based SaaS apps.
• You need a consistent blueprint that includes frontend, backend, authentication, payments, and deployment rules.
• You plan to standardize project structure and security practices across teams.

Copyable CLAUDE.md Template

# CLAUDE.md

Project role: You are a software architect and developer tasked with building a production-grade Subscription SaaS using Angular Material on the frontend and FastAPI on the backend.

Architecture rules:
- Monorepo with separation between frontend and backend.
- Backend endpoints for users, plans, subscriptions, invoices, and webhooks.
- PostgreSQL as the primary data store; Alembic for migrations.
- Stripe for subscription management; webhooks configured for events.
- JWT-based authentication; access and refresh tokens with short lifetimes.
- Use Docker for local development; docker-compose to run frontend, backend, and postgres.
- Environment-specific configs (dev/stage/prod).

File structure rules:
- Frontend code under frontend/
- Backend code under backend/
- Infra and deployment under infra/
- Secrets injected via env vars, not hardcoded.

Authentication rules:
- JWT access token in Authorization header: Bearer 
- Refresh tokens rotated on use; store hashes, not tokens, in DB.

Database rules:
- Use PostgreSQL with strict typing; enforce foreign keys and constraints.
- Migrate with Alembic; seeds via a seed script.

Validation rules:
- Validate all inputs with Pydantic schemas; return 400 on validation errors.

Security rules:
- Do not log secrets or full tokens.
- Always serve over HTTPS in production; CORS restricted to allowed origins.
- Validate Stripe webhooks with signature verification.

Testing rules:
- Backend: unit tests for service logic and API tests for endpoints.
- Frontend: unit tests for components and services; end-to-end tests via Playwright.
- Run tests in CI on push to main/marge.

Deployment rules:
- Use docker-compose for local development.
- Provide Dockerfiles for frontend and backend; build and run in prod if needed.
- Use environment variables for credentials; never commit secrets.

Things Claude must not do:
- Do not generate code that bypasses authentication.
- Do not expose secret keys in code or logs.
- Do not configure permissive CORS in prod.
- Do not assume sandbox payment behavior; validate webhooks in production.

Recommended Project Structure

frontend/
  angular.json
  package.json
  tsconfig.json
  src/
    app/
    assets/
    environments/
backend/
  main.py
  app/
  requirements.txt
  alembic/
infra/
  docker-compose.yml
  Dockerfile.frontend
  Dockerfile.backend

Core Engineering Principles

• Define a clear monorepo boundary with strict module interfaces.
• Prefer explicit types and schemas (Pydantic for backend, TypeScript for frontend).
• Automate tests, linting, and type checks in CI.
• Guard secrets and credentials using environment variables and secret stores.
• Ensure production-grade security: authenticated endpoints, validated inputs, and encrypted data at rest.

Code Construction Rules

• Frontend: Use Angular with Material components and feature modules; adhere to a strict component architecture.
• Backend: FastAPI endpoints map to resources (users, plans, subscriptions); use Pydantic models for IO and SQLAlchemy for persistence.
• Payment: Stripe integration with product plans and webhook handling; verify signatures on webhooks.
• Auth: JWT with short-lived access tokens; securely store refresh tokens.
• Deployment: Dockerized services; use docker-compose for local development; promote to prod with proper env vars.

Security and Production Rules

• Never hardcode secrets; use environment variables and secret management.
• Enable HTTPS, enforce strong CORS policies, and validate Stripe webhook signatures.
• Limit API rate limits and monitor for anomalous activity.
• Audit logging without exposing sensitive data.

Testing Checklist

• Unit tests for backend services and frontend components.
• Integration tests for authentication, subscription flow, and webhook events.
• End-to-end tests simulating a user sign-up, plan selection, and checkout.
• CI checks: lint, type checks, tests, and build verification.

Common Mistakes to Avoid

• Hardcoding secret keys in code or config files.
• Misconfiguring Stripe webhook endpoints or relying on test mode in prod.
• Using overly permissive CORS in production.
• Skipping migrations or ignoring data migrations in production upgrades.

FAQ