Angular Material + FastAPI Firebase Auth CLAUDE.md Template

Overview

The CLAUDE.md template provides a ready-to-paste CLAUDE.md block that scaffolds an Angular Material frontend with a FastAPI backend and Firebase Authentication. It defines architecture, file layout, auth flow, and production considerations for this stack. This page is a copyable CLAUDE.md template page designed for developers looking to bootstrap this stack quickly. Direct answer: use the template to generate a cohesive, secure starter for Angular Material + FastAPI + Firebase Auth.

When to Use This CLAUDE.md Template

• Starting a new project with an Angular Material frontend, FastAPI API, and Firebase Auth.
• Seeking a consistent CLAUDE.md starter to guide Claude Code in code generation and security rules.
• Desiring a repeatable directory structure and a clear set of validation and deployment rules.

Copyable CLAUDE.md Template

# CLAUDE.md
Project role: You are an expert full-stack engineer who produces a ready-to-run starter for the Angular Material + FastAPI + Firebase Auth stack. The output must be a complete, copyable starter that Claude Code can execute to generate scaffold code.

Architecture rules:
- Frontend and backend are decoupled via a REST API layer.
- Use Firebase ID tokens for authentication; backend must verify tokens with the Firebase Admin SDK.
- Backend uses PostgreSQL via SQLAlchemy; migrations via Alembic.
- All secrets are loaded from environment variables; no hard-coded credentials.
- API versioning via v1 namespace; consistent response shapes.

File structure rules:
- Frontend: angular material SPA in frontend/.
- Backend: FastAPI app in backend/.
- Shared types in common/ (client-models and server-models); avoid duplicating types in code.
- Docker-related configs in docker/.

Authentication rules:
- Client obtains Firebase ID token after Sign-In with Firebase Auth (email/password or provider).
- All /api/v1/* endpoints require Authorization: Bearer .
- Backend validates token; on success, attaches user info to request state.

Database rules:
- PostgreSQL is the primary store for user profiles and application data.
- Tables: users (id, firebase_uid, email, display_name, created_at), items (id, owner_id, payload, created_at).
- Use SQLAlchemy models with proper constraints; include created_at timestamps set by the server.

Validation rules:
- Pydantic models for all request/response payloads.
- Strict typing; no implicit any types.
- Validate IDs, emails, and payload schemas before processing.

Security rules:
- Enforce HTTPS; disable insecure endpoints in production.
- Do not log sensitive data (tokens, emails, or secrets).
- Use CORS with whitelisting for frontend domain.
- Never expose Firebase Admin credentials on the client; store securely on the server.

Testing rules:
- Backend: unit tests for models and services with pytest; integration tests for API endpoints with TestClient.
- Frontend: unit tests with Jest or Vitest; E2E tests with Playwright focused on auth flow and common UI paths.
- Local development uses docker-compose to run frontend and backend with a local Postgres instance.

Deployment rules:
- Dockerfiles for frontend and backend; docker-compose.yml for local dev and production deployments.
- CI: lint, test, build; push to registry; deploy to cloud with environment variables supplied.
- Ensure Firebase credentials (service account) are provided via environment or secret manager at runtime.

Things Claude must not do:
- Do not generate client-side code that embeds Firebase Admin credentials.
- Do not create endpoints that bypass token verification or expose user data without auth.
- Do not loosen CORS beyond the explicit allowlist.
- Do not use insecure HTTP in production; always enable HTTPS.

Recommended Project Structure

frontend/
  src/
    app/
      app.module.ts
      app.component.ts
      components/
      services/
      pages/
    assets/
  index.html
  angular.json
backend/
  app/
    main.py
    api/
      v1/
        endpoints/
          users.py
          items.py
    models/
      user.py
      item.py
    core/
      config.py
      auth.py
    firebase/
      firebase_admin.py
  requirements.txt
docker-compose.yml
Dockerfile.frontend
Dockerfile.backend
.env
README.md

Core Engineering Principles

• Explicit architecture: clear separation between UI, API, and data layers.
• Type safety: use TypeScript interfaces on the frontend and Pydantic models on the backend.
• Security-first defaults: deny by default; enable access with explicit rules and validated tokens.
• Be production-ready: test coverage, logging, observability, and reproducible builds.
• Accessibility and UX: Angular Material components follow accessible patterns.

Code Construction Rules

• Frontend uses Angular Material and reactive forms; components must be lazy-loaded and accessible.
• Attach Firebase ID tokens to API requests via an HttpInterceptor; refresh tokens securely as needed.
• Backend endpoints use FastAPI with Pydantic models; all responses are JSON with a consistent envelope.
• Firebase Admin SDK is used server-side to verify ID tokens; do not verify on the client.
• Database access uses SQLAlchemy with proper session management and Alembic migrations.
• Validate and sanitize all inputs; do not trust client payloads.
• Do not bypass authentication on any protected endpoint.
• Do not embed Firebase credentials in frontend code.
• Do not rely on permissive CORS in production.

Security and Production Rules

• Use HTTPS; enforce HSTS where possible.
• Store Firebase service account credentials securely; use secret managers.
• Audit logs for auth attempts and important state changes; avoid logging tokens.
• Implement rate limiting and proper error handling to prevent data leakage.
• Protect against SQL injection with ORM and parameterized queries.

Testing Checklist

• Unit tests for Pydantic models and utility services.
• Integration tests for /api/v1/* endpoints with token-based auth using a test Firebase project.
• Frontend tests for UI components and token flow; verify material theming and accessibility.
• End-to-end tests for sign-in, token propagation, and a protected data path.
• CI runs lint, test, and build; production-like Docker images built in CI.

Common Mistakes to Avoid

• Assuming the client can verify Firebase tokens; verification must occur on the server.
• Hard-coding secrets or Firebase Admin credentials in frontend code.
• Overly permissive CORS policies in production.
• Skip tests or insufficient test coverage for authentication and data access paths.

FAQ

Q: What is this CLAUDE.md Template used for?

A: It provides a copyable CLAUDE.md template to bootstrap an Angular Material + FastAPI + Firebase Auth starter and to guide Claude Code generation.

Q: Which stack does it cover?

A: Angular Material frontend, FastAPI backend, and Firebase Authentication.

Q: How do I customize the template for my project?

A: Edit the CLAUDE.md block to reflect your project role, architecture, and file structure; adjust environment variables and token handling accordingly.

Q: How do I test the generated starter?

A: Run backend tests with pytest, frontend tests with npm test or Playwright, and verify token authentication in a staging environment.

Q: Where should I deploy this starter?

A: Dockerize the frontend and backend and deploy to your cloud provider with proper secrets management.