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

Overview

This CLAUDE.md template describes a copyable Claude Code starter for a full-stack application built with Angular Material for the frontend, FastAPI for the backend, and Supabase Storage for file handling. It covers architecture, project structure, authentication, and production considerations so developers can paste a ready-to-use CLAUDE.md into their repository.

Direct answer summary: Use this CLAUDE.md template to scaffold a consistent, secure, and testable Angular Material + FastAPI + Supabase Storage project with Claude Code guidance embedded in the README.

When to Use This CLAUDE.md Template

• You are starting a new project with Angular Material-based UI, a FastAPI backend, and Supabase Storage for assets/files.
• You want a single CLAUDE.md to enforce architecture, security, and deployment rules across frontend, backend, and storage components.
• You need a reproducible structure for onboarding, CI/CD, and deployment pipelines.
• You require Claude Code to produce concrete, stack-specific instructions that are copy-paste friendly.

Copyable CLAUDE.md Template

# CLAUDE.md

Project role
- You are Claude, producing a ready-to-use scaffold for an Angular Material + FastAPI + Supabase Storage stack. Your output must be a clean, copy-pasteable CLAUDE.md block that developers can drop into their repository README.

Architecture rules
- Frontend: Angular Material v15+ with a component-driven structure; use HttpClient for API calls.
- Backend: FastAPI v0.118+ with Pydantic models; JWT-based authentication; API versioning under /api/v1.
- Storage: Supabase Storage for user assets; use signed URLs for secure access; do not expose raw storage keys in client code.
- API contracts: RESTful endpoints with clear request/response schemas; versioned routes (e.g., /api/v1/files).
- Environment separation: create dev/staging/prod configurations; use .env files and Docker for local development.
- Secrets: never commit secrets; fetch at runtime from a vault or environment variables.

File structure rules
- Frontend lives in frontend/ with Angular app under frontend/src/app/*
- Backend lives in backend/ with FastAPI app under backend/app/
- Infrastructure and storage rules live under infra/ (e.g., infra/supabase/ for storage policies)
- Do not mix concerns across folders (frontend vs backend vs infra).

Authentication rules
- Use JWTs returned from backend to authorize frontend requests.
- Protect endpoints with FastAPI dependencies verifying token scopes.
- For file uploads, generate time-limited signed URLs from the backend for the client to upload/download.

Database rules
- Use Supabase (PostgreSQL) with well-defined tables: users, files, file_metadata.
- Enforce NOT NULL constraints and proper foreign keys.
- Validate input with Pydantic models; return 400 for validation errors.

Validation rules
- All inputs must be validated server-side; front-end inputs must be sanitized and type-checked.
- Validate file sizes, MIME types, and bucket permissions for storage interactions.

Security rules
- Use HTTPS; enable CORS only for the frontend origin.
- Rotate secrets periodically and audit access logs.
- Disable eager file listing; require signed URLs for access.

Testing rules
- Backend: unit tests for models, dependencies, and endpoints (pytest); integration tests for API and storage URL generation.
- Frontend: unit tests for components/services (Jest); end-to-end tests with Cypress for /api/v1 interactions.
- CI should run tests on PRs and require successful tests before merge.

Deployment rules
- Dockerize frontend and backend; use docker-compose for local development.
- Deploy to a cloud provider with a managed PostgreSQL/ Supabase instance and CDN for assets.
- Include health checks and metrics endpoints.

Things Claude must not do
- Do not assume Prisma or Mongoose usage in this stack.
- Do not embed secrets or credentials in code blocks.
- Do not recommend incompatible libraries for this stack (e.g., using Django ORM).

Recommended Project Structure

root/
├── frontend/
│   ├── src/
│   │   ├── app/
│   │   │   ├── components/
│   │   │   ├── services/
│   │   └── index.html
│   ├── angular.json
│   └── package.json
├── backend/
│   ├── app/
│   │   ├── api/
│   │   │   ├── v1/
│   │   │   │   ├── endpoints/
│   │   │   │   └── models/
│   │   └── main.py
│   ├── requirements.txt
│   └── Dockerfile
├── infra/
│   └── supabase/
│       ├── storage-policies/
│       └── docker-compose.yml
└── README-clause.md

Core Engineering Principles

• Separation of concerns: frontend, backend, and storage config stay in distinct folders with clear interfaces.
• Security-by-default: use signed URLs, token-based auth, proper CORS, and never expose secrets.
• Reproducible builds: dockerize and pin dependencies; use environment-aware configurations.
• Type safety and validation: rely on Pydantic on the backend and TypeScript types on the frontend.
• Observability: log structured events, enable health checks, and monitor storage access.

Code Construction Rules

• Frontend should be Angular Material components with modular routing and lazy loading.
• Backend endpoints must be versioned and documented with typed request/response models.
• Use Pydantic models for validation; return clear error payloads for invalid input.
• Storage interactions must use signed URLs for uploads/downloads; do not expose bucket keys.
• All code comments should explain intent, not obvious implementation details.
• Do not use unsupported libraries; keep to FastAPI, Python, Angular, and Supabase SDKs.

Security and Production Rules

• Enable HTTPS in all environments; enforce secure cookies and JWT storage best practices.
• Limit CORS to the frontend domain; enable rate limiting on critical endpoints.
• Rotate API keys and service roles; audit storage access logs regularly.
• Use least-privilege roles for Supabase storage and database access.

Testing Checklist

• Unit tests for backend models and helpers; mock storage signed URL generation.
• Integration tests for /api/v1 endpoints including file upload/download flows.
• Frontend unit tests for components and services; end-to-end tests for API interactions.
• CI should run linting, tests, and type checks; deploy previews for PRs.

Common Mistakes to Avoid

• Ignoring signed URL security; exposing raw storage endpoints.
• Overcomplicating API schemas; keep consistent DTOs and avoid duplicate models.
• Hardcoding environment values in source; prefer runtime configuration.
• Skipping tests for storage interactions; assume storage is always available.

FAQ

What is included in this CLAUDE.md Template?

A ready-to-paste CLAUDE.md block plus stack-specific project structure, rules, and security guidance for Angular Material + FastAPI + Supabase Storage.

Can I adapt this template to different Angular or FastAPI versions?

Yes. It emphasizes versioned routes, environment separation, and testability; adjust versions in your local repo as needed.

How are storage credentials handled?

Use signed URLs generated on the backend; never expose storage keys to the client.

What should I customize after pasting?

Update endpoints, storage bucket names, environment variables, and any domain-specific validation rules for your app.

Is this suitable for production?

Yes, but ensure you adapt it to your CI/CD, monitoring, and governance requirements; this template provides a solid baseline.