Angular Material + FastAPI Task Management CLAUDE.md Template

Overview

CLAUDE.md templates are concrete, copyable Claude Code starter blocks designed for a specific stack. This page provides a full CLAUDE.md Template for an Angular Material frontend paired with a FastAPI backend to implement a task management application. It includes a practical code block, a stack-aligned project structure, security and deployment guidance, and QA checks. Direct answer: you can paste the included Claude Code block into a CLAUDE.md file to bootstrap the project scaffolding and governance for this stack.

When to Use This CLAUDE.md Template

• Starting point for a full-stack Angular Material + FastAPI task manager.
• Standardized CLAUDE Code instructions for frontend-backend coordination.
• Educational reference for API design, auth, validation, and deployment in this stack.

Copyable CLAUDE.md Template

# CLAUDE.md

Project role: Frontend Developer / Backend Integrator for an Angular Material + FastAPI task management app.

Architecture rules:
- Build a REST API in FastAPI exposing /api/v1/tasks and /api/v1/users with JSON payloads.
- Use Pydantic models for request/response validation.
- Keep frontend in an Angular Material powered app consuming the API with HttpClient.
- Ensure OpenAPI docs exposure and strong typing across layers.
- Use HTTP-only cookies for refresh tokens and Authorization header for access tokens.
- Follow a clear 3-tier architecture: UI, API, and data access.

File structure rules:
- Frontend in angular-app (Angular CLI project) with material modules and a feature-based layout.
- Backend in backend/app with routers, models, schemas, and services.
- No mixing of frontend and backend code in the same module.

Authentication rules:
- JWT-based authentication using OAuth2PasswordBearer-like flow.
- Access token in Authorization header: Bearer <token>.
- Refresh tokens stored in HTTP-only cookies with rotation strategy.

Database rules:
- PostgreSQL as the primary DB.
- SQLAlchemy models for ORM; Pydantic schemas for IO validation.
- Use Alembic migrations for schema changes.

Validation rules:
- Validate inputs via Pydantic BaseModel.
- Enforce required fields, length constraints, and type checks.
- Normalize and sanitize strings to guard against injection.

Security rules:
- Never hard-code secrets; load from environment variables.
- Use HTTPS in production; enable CORS for frontend domain only.
- Protect endpoints under /api/v1 with authentication guards.
- Do not log sensitive payloads in production logs.

Testing rules:
- Unit tests for FastAPI endpoints using pytest + httpx.
- Integration tests covering auth flows and CRUD for tasks.
- Frontend tests using Angular testing tools for components interacting with the API.

Deployment rules:
- Dockerize frontend (Angular) and backend (FastAPI) with a shared docker-compose setup.
- Use environment variables for DB connection, JWT secrets, and CORS origins.
- Run migrations during deployment; smoke tests post-deploy.

Things Claude must not do:
- Do not generate insecure tokens or embed secrets in code.
- Do not bypass authentication checks or expose admin endpoints publicly.
- Do not assume a specific database; parameterize DB type via config where possible.

Recommended Project Structure

frontend/
  angular-app/
    src/
      app/
        components/
        pages/
        services/
      assets/
    angular.json
    package.json
    tsconfig.json
backend/
  app/
    main.py
    api/
      v1/
        endpoints/
        models.py
        schemas.py
        routers.py
  config/
  requirements.txt
  Dockerfile
  docker-compose.yml

Core Engineering Principles

• Clear separation of concerns: frontend UI, API layer, and data access.
• Strong typing: use Pydantic for FastAPI input/output, and TypeScript for Angular.
• Security by design: token-based auth, proper CORS, and least-privilege access.
• Idempotent and deterministic operations for CRUD actions.
• Automated tests and reproducible deployments.

Code Construction Rules

• Endpoints under /api/v1 should be RESTful and versioned.
• Use Pydantic models for both request validation and response schemas.
• Angular services should encapsulate API calls with typed interfaces.
• Frontend components must consume the API via HttpClient with proper error handling.
• Config-driven behavior: API base URL and feature flags from environment/config files.
• Do not hard-code secrets or credentials in code or config files checked into VCS.

Security and Production Rules

• Use HTTPS, enable CORS for the frontend domain only.
• Store refresh tokens in HTTP-only cookies; keep access tokens in memory or local storage as RFC-compliant.
• Validate all inputs server-side; never trust client data.
• Use Alembic for migrations; review migrations before applying to production.
• Rotate secrets; use a secret manager where possible.

Testing Checklist

• Unit tests for each FastAPI endpoint with fixtures for test database.
• Integration tests that cover auth flows and task CRUD scenarios.
• Frontend component tests verifying API integration and form validation.
• End-to-end tests that simulate user task creation, update, and deletion.
• CI checks for linting, typing, and test suites; ensure Docker image builds pass.

Common Mistakes to Avoid

• Bypassing authentication for internal endpoints.
• Hard-coded tokens or secrets in CLAUDE.md templates.
• Assuming a specific database without config-driven adapters.
• Over-fetching data in API responses; return only necessary fields.
• Ignoring CORS and HTTPS in production.

FAQ

What is this CLAUDE.md Template for Angular Material + FastAPI Task Management?

The template provides a copyable Claude Code starter for a full-stack app with an Angular Material UI and a FastAPI backend focused on task management.

Which stack components are covered?

Angular Material UI, FastAPI API layer, PostgreSQL/SQLAlchemy data layer, JWT-based authentication, and deployment best practices.

How do I run this locally?

Install frontend dependencies, run the FastAPI server, configure environment variables, and start both services via docker-compose or separate commands as documented in the CLAUDE.md.

How do I secure the API?

Use JWT access tokens in the Authorization header, refresh tokens in HTTP-only cookies, enable CORS for the frontend domain, and store secrets in environment variables.

How can I customize endpoints for additional resources?

Extend routers.py in FastAPI, add Pydantic models, and create corresponding Angular services and components to consume them.