CLAUDE.md Template: Angular Material + FastAPI SQLAlchemy

Overview

This CLAUDE.md template page demonstrates a copyable Claude Code starter for a stack combining Angular Material frontend, FastAPI backend, and SQLAlchemy ORM. It provides tightly-scoped guidance to generate a cohesive end-to-end project with clear separation of concerns, typed data contracts, and secure defaults suitable for production-ish development environments.

Direct answer: Use this CLAUDE.md Template to rapidly scaffold a consistent Angular Material + FastAPI + SQLAlchemy project with Claude Code rules that enforce architecture, testing, security, and deployment constraints.

When to Use This CLAUDE.md Template

• You need a reproducible skeleton for a modern Angular UI with Material components paired to a FastAPI REST API backend.
• You require SQLAlchemy ORM models and schemas aligned with Pydantic-like validation in the backend and TypeScript interfaces in the frontend.
• You want a copyable CLAUDE.md to guide Claude Code into producing consistent project scaffolding, tests, and deployment configs.
• You are setting up a template that can be reused across multiple frontend-backend pairs with minimal divergence.

Copyable CLAUDE.md Template

# CLAUDE.md

Project role:
- You are Claude Code. You generate a full-stack scaffold with an Angular Material frontend, a FastAPI backend, and SQLAlchemy ORM models. You enforce modular boundaries, typed contracts, and predictable workflows to support rapid development and maintainability.

Architecture rules:
- Separate frontend and backend into distinct domains: frontend/angular-app and backend/app.
- Use RESTful endpoints with clear resources and versioning if needed.
- Centralize data contracts via shared models between frontend and backend where feasible.
- Prefer containerized services for dev and prod parity.

File structure rules:
- Frontend resides in frontend/angular-app with standard Angular CLI layout.
- Backend resides in backend/app with routers, services, schemas, models, and core config.
- All tests live under respective test folders: frontend/test and backend/tests.
- Use Docker for dev and deployment; include docker-compose.yml for local runs.

Authentication rules:
- Use OAuth2 with JWT access tokens for the API.
- FastAPI dependencies should validate tokens on protected routes.
- Do not return sensitive token info in responses.

Database rules:
- SQLAlchemy models for all persistence. Use Alembic for migrations.
- Use PostgreSQL in prod; SQLite for local dev with a switchable config.
- Enforce proper relationships, indices, and constraints.

Validation rules:
- Pydantic models on the backend for request validation.
- On the frontend, TypeScript interfaces for API payloads with runtime checks where needed.

Security rules:
- Disable CORS in production unless required; whitelist trusted origins.
- Do not disable HTTPS in production; prefer secure cookies and JWTs with short lifetimes.
- Never log secrets or database connection strings.

Testing rules:
- Backend: unit tests for models and services; integration tests for endpoints.
- Frontend: unit tests for components and services; basic end-to-end tests if feasible.
- Include CI hooks for running tests on PRs.

Deployment rules:
- Provide a Dockerfile for frontend and backend; docker-compose for dev orchestrations; use environment variables for secrets.
- Set up health checks and reload strategies for container restarts.
- Include a minimal CI/CD pipeline example in docs.

Things Claude must not do:
- Do not embed secrets or passwords.
- Do not generate code that uses insecure secret handling or eval() unsafely.
- Do not assume a specific cloud provider beyond recommended defaults.
- Do not bypass input validation or authentication checks.

Recommended Project Structure

angular-fastapi-sqlalchemy-starter/
├── frontend/
│   └── angular-app/
│       ├── src/
│       │   ├── app/
│       │   │   ├── components/
│       │   │   ├── pages/
│       │   │   └── app.module.ts
│       │   ├── assets/
│       │   └── index.html
│       ├── angular.json
│       └── package.json
├── backend/
│   └── app/
│       ├── main.py
│       ├── api/
│       │   ├── v1/
│       │   │   └── routers/
│       │   └── dependencies.py
│       ├── models/
│       ├── schemas/
│       ├── core/
│       ├── config.py
│       └── database.py
├── alembic/
├── docker-compose.yml
├── Dockerfile-frontend
├── Dockerfile-backend
└── README.md

Core Engineering Principles

• Explicit contracts between frontend and backend with shared data models.
• Type safety across stack: TypeScript interfaces and Pydantic models.
• Single source of truth for API schemas and UI data shapes.
• Security by default: validated inputs, least privilege, and secrets management.
• Observability: structured logs, tracing, and metrics from both sides.
• Deterministic builds and reproducible environments via Docker and CI.

Code Construction Rules

• Frontend components must use Angular Material components with accessible labels and ARIA attributes.
• Backend endpoints should be modular: routers for each resource, with dependency injection for services.
• SQLAlchemy models must include __tablename__, primary keys, and relation mappings; migrations via Alembic.
• Data validation must be performed server-side using Pydantic-like schemas and client-side TypeScript interfaces.
• Environment-specific configs must be isolated and sourced from environment variables.
• Frontend requests must handle errors gracefully and show user-friendly messages.

Security and Production Rules

• JWT-based authentication with short-lived tokens and refresh flow.
• CORS restricted to known origins; CSRF protection where applicable.
• Secrets never stored in code; use environment managers and secret stores.
• Database connections secured with TLS in production; rotate credentials regularly.
• Input validation, escaping, and output encoding to prevent injection attacks.
• Logging should redact sensitive fields; monitor anomalies via alerts.

Testing Checklist

• Backend: unit tests for models, services, and validators; integration tests for API endpoints.
• Frontend: unit tests for components and services; e2e tests for key flows if feasible.
• Run tests in CI on PRs; require coverage thresholds for critical modules.
• Verify migrations apply cleanly in a test database.
• Smoke tests for docker-compose-based dev environment.

Common Mistakes to Avoid

• Skipping input validation on endpoints or UI forms.
• Overexposing API data or secret keys in responses.
• Inconsistent data models between frontend and backend contracts.
• Ignoring accessibility when using Angular Material components.
• Assuming frontend state exactly mirrors backend data; ensure explicit mappings.

FAQ

What is this CLAUDE.md Template for?

A copyable CLAUDE.md template page to scaffold an Angular Material frontend with a FastAPI backend and SQLAlchemy ORM, with Claude Code rules for consistent generation.

Which stack does it cover?

Angular Material UI + FastAPI REST API + SQLAlchemy ORM with a modular project structure.

What should I paste into Claude?

Paste the entire code block under Copyable CLAUDE.md Template into your CLAUDE.md file and customize as needed for your project.

How do I run this locally?

Start the frontend with npm install & npm start in frontend/angular-app, and start the backend with uvicorn using the backend/app main module; use docker-compose for an integrated run.

Is authentication included?

Yes. The template prescribes JWT-based authentication for the API and protected routes in FastAPI.