Angular Material + FastAPI Developer Portal CLAUDE.md Template

Overview

CLAUDE.md Template for an Angular Material + FastAPI Developer Portal provides a structured CLAUDE.md block you can copy-paste into Claude Code. It targets a frontend built with Angular Material and a backend implemented with FastAPI, and it enforces stack-specific conventions for architecture, security, testing, and deployment. Direct answer: this page delivers a ready-to-use, stack-specific CLAUDE.md Template that you can drop into your Claude Code workspace to accelerate portal development.

When to Use This CLAUDE.md Template

• Starting a new Developer Portal project with Angular Material frontend and FastAPI backend.
• Seeking a consistent CLAUDE.md instruction block for the Angular + FastAPI stack.
• Documenting architecture, auth flow, and deployment rules in a shareable CLAUDE.md format.
• Onboarding new engineers with a stack-specific CLAUDE.md baseline.

Copyable CLAUDE.md Template

# CLAUDE.md

Project role: You are Claude Code helping build an Angular Material + FastAPI Developer Portal. You provide architecture guidance, secure patterns, and a copyable CLAUDE.md block for this stack.

Architecture rules:
- API-first contract driven by an OpenAPI spec; ensure frontend and backend share data shapes.
- SPA frontend (Angular Material) talks to FastAPI backend via REST; avoid leaking business logic to the frontend.
- Backend uses PostgreSQL with SQLAlchemy and Alembic for migrations; keep models separate from API schemas.
- Separate concerns: controllers handle requests, services contain business logic, and repositories manage persistence.
- Generate and keep OpenAPI docs synchronized with code.

File structure rules:
- Frontend at frontend/ with src/app structure and Angular-specific config at the root of frontend/.
- Backend at backend/ with app/, core/, and db/ folders; include a Dockerfile for each service.
- Shared types live under a common/ or shared/ module to align frontend and backend contracts.

Authentication rules:
- Use OAuth2 with PKCE for the SPA; issue access tokens from the backend and validate on every request.
- Do not store tokens in localStorage; prefer memory storage or secure cookies for refresh tokens if used.
- Protect sensitive endpoints with proper scopes/roles and verify tokens on the backend.

Database rules:
- PostgreSQL as the primary database; define models with SQLAlchemy and enforce migrations with Alembic.
- Use parameterized queries and proper validation for all inputs.

Validation rules:
- Pydantic models for all request/response payloads in FastAPI; validate strictly and fail fast on invalid data.
- Angular forms should use strong typing and runtime validators for user input.

Security rules:
- Enforce HTTPS in all environments; configure CORS to allow only trusted origins.
- Validate JWT signatures, audience, and expiration on each API call.
- Disable endpoints that expose sensitive data; implement rate limiting where appropriate.

Testing rules:
- Backend: unit tests for models/services with pytest; integration tests for endpoints using httpx.
- Frontend: unit tests for components/services with Angular testing tools; end-to-end tests with Cypress.
- CI to run full test suite on PRs and enforce code quality gates.

Deployment rules:
- Use docker-compose for local development; separate images for frontend and backend.
- Build pipelines should run tests, linting, and type checks before deployment.
- Secrets must be injected via environment variables; do not commit credentials.

Things Claude must not do:
- Do not bypass authentication checks or proxy user credentials insecurely.
- Do not embed backend business logic in the frontend bundle.
- Do not rely on localStorage for tokens or sensitive data.

Recommended Project Structure

frontend/
  src/
    app/
      core/
      features/
      shared/
      app.module.ts
      app-routing.module.ts
    index.html
  angular.json
  package.json
  tsconfig.json
backend/
  app/
    main.py
    api/
      v1/
        endpoints/
        models/
        routers/
    core/
      config.py
      security.py
  requirements.txt
  Dockerfile
  docker-compose.yml
README.md

Core Engineering Principles

• API contracts drive both frontend and backend using OpenAPI specs.
• End-to-end type safety between Angular (TypeScript) and FastAPI (Pydantic models).
• Automated tests, clear CI/CD, and deterministic deployments.
• Separation of concerns: frontend, backend, and data access layers are distinct.
• Security-first design: HTTPS, proper auth, and input validation by default.

Code Construction Rules

• Frontend: Angular with strict TS config; use Angular Material components from official packages only.
• Backend: FastAPI with Pydantic models; SQLAlchemy + Alembic for PostgreSQL migrations.
• Router handlers should delegate to services; avoid embedding business logic in routes.
• OpenAPI specs must be generated and synchronized with code changes.
• All API responses must conform to declared Pydantic models and types.

Security and Production Rules

• Enforce HTTPS in all environments; configure strict CORS origins.
• Token-based authentication with JWT; do not store tokens insecurely in the browser.
• Use HTTP-only cookies for refresh tokens if cookie-based flows are implemented.
• Validate all inputs; implement CSRF protection for state-changing requests in SPA if cookies are used.

Testing Checklist

• Backend: unit tests for models/services; integration tests for API endpoints.
• Frontend: unit tests for components/services; UI tests for Material components.
• End-to-end: test login flow, portal navigation, and API interactions.
• CI: run tests and linting on every PR; ensure code quality gates pass.

Common Mistakes to Avoid

• Assuming browser storage is safe for tokens; avoid localStorage for sensitive data.
• Coupling frontend routes too tightly to backend implementation details.
• Drifting OpenAPI contracts without syncing changes in code.
• Skipping migrations or relying on in-container data persistence without proper scripts.

FAQ

• Q: What is this CLAUDE.md Template for Angular Material + FastAPI Developer Portal?
  A: It provides a ready-to-paste CLAUDE.md block and stack-specific guidance to scaffold an Angular Material frontend with a FastAPI backend for a developer portal.
• Q: How do I customize the CLAUDE.md template for my project?
  A: Replace the code block details with your API contracts, auth flow, and directory layout while keeping the required sections.
• Q: Where should I paste the CLAUDE.md template?
  A: In your CLAUDE.md file within your Claude Code workspace for this stack.
• Q: What should the authentication flow look like?
  A: Use OAuth2 with PKCE for the SPA; issue and validate tokens on the backend; refresh tokens may use HTTP-only cookies.
• Q: What database setup is assumed?
  A: PostgreSQL with SQLAlchemy in the FastAPI backend; use Alembic for migrations.