CLAUDE.md Template + CLAUDE.md template: Angular Material + FastAPI + Supabase

Overview

CLAUDE.md template is a copyable Claude Code instruction block designed for a specific stack. This page provides a ready-to-paste CLAUDE.md template for an Angular Material + FastAPI + Supabase starter. It enables a reproducible frontend/backend/auth blueprint that teams can drop into a new project.

The stack covered here combines an Angular Material based frontend, a FastAPI backend, and Supabase for authentication and a Postgres database. Claude Code users paste the block below into CLAUDE.md to guide the implementation step by step.

When to Use This CLAUDE.md Template

• Starting a new full stack project that uses Angular Material on the frontend, FastAPI on the backend, and Supabase as the auth and database layer.
• You want a reproducible, copyable instruction block to onboard new engineers quickly.
• You require a contract between frontend and backend with concrete file structure, rules, and deployment steps.

Copyable CLAUDE.md Template

# CLAUDE.md
Project role: You are Claude Code, an AI assistant that generates exact, copyable instructions for building a full stack Angular Material + FastAPI + Supabase starter. Do not add nonessential steps.

Architecture rules:
- Frontend: Angular with Angular Material
- Backend: FastAPI
- Auth/DB: Supabase
- Communication via REST APIs; avoid GraphQL unless requested
- Separate concerns: frontend, backend, infra

File structure rules:
- frontend/ as the Angular project root
- backend/ as the FastAPI project root
- infra/ for deployment and environment guidance

Authentication rules:
- Frontend authenticates with Supabase Auth; backend validates Supabase JWTs on protected endpoints
- Do not rely on client-only authentication for sensitive operations

Database rules:
- Use Supabase Postgres; define minimal schemas named users and items
- Do not seed production data in templates

Validation rules:
- FastAPI uses Pydantic models for request and response validation
- Mirror server-side validation on the frontend forms

Security rules:
- Do not commit secrets; read from environment variables
- Enforce CORS properly; enable TLS in production
- Do not expose admin endpoints without proper authorization

Testing rules:
- Unit tests for FastAPI endpoints
- Integration tests for auth flows and data access
- Use pytest; mock external services where appropriate

Deployment rules:
- Provide a docker-compose.yml to run frontend and backend together
- Document required environment variables and secrets placeholders

Things Claude must not do:
- Do not bypass authentication
- Do not seed production data
- Do not disable input validation

Recommended Project Structure

frontend/
  angular.json
  package.json
  src/
    app/
      app.module.ts
      app.component.ts
      components/
      services/
      pages/
    assets/
    environments/
  tsconfig.json

backend/
  main.py
  requirements.txt
  app/
    api/
      v1/
        endpoints/
        routers/
    models/
    schemas/

infra/
  docker-compose.yml
  .env.example
  README.md

Core Engineering Principles

• Clear separation of frontend, backend, and infra concerns
• Type safety and explicit contracts between layers
• Reproducibility through a well defined project structure
• Security first, with environment based configuration
• Observable and testable codepaths with clear error handling
• Minimal, purposeful dependencies

Code Construction Rules

• Use Angular Material components with accessible ARIA labels
• Centralize API base URLs in environment files; avoid hard coded strings
• FastAPI endpoints should rely on Pydantic models for request and response bodies
• Validate and sanitize all inputs on server side; mirror on client side
• Use Supabase JS client on the frontend for auth and data operations
• Validate Supabase JWTs on the FastAPI backend for protected routes
• Do not couple frontend and backend with nonstandard auth flows
• Do not rely on client side only authorization for sensitive operations

Security and Production Rules

• Do not commit secrets; use environment variables and secret management
• Enforce strict CORS policies and TLS in production
• Use Role-Based Access Control for database access where applicable
• Audit logs and error handling; avoid leaking stack traces in responses

Testing Checklist

• Unit tests for FastAPI endpoints with mocked DB calls
• Integration tests that cover auth flows and data access
• Linting and type checks in both frontend and backend
• Lightweight end-to-end checks for critical user journeys (optional in this starter)

Common Mistakes to Avoid

• Skipping server side validation in FastAPI
• Bypassing JWT checks on protected endpoints
• Storing secrets in source control
• Overloading the frontend with business logic that belongs on the backend

FAQ