CLAUDE.md Template: Angular Material + FastAPI CRM Starter

Overview


  This CLAUDE.md template provides a start-to-finish CLAUDE Code block for a CRM stack that combines an Angular Material frontend with a FastAPI backend. It targets strong type contracts between layers, secure authentication, and a maintainable project structure. Direct answer: this page delivers a copyable CLAUDE.md template ready to paste into CLAUDE.md for a full-stack Angular Material + FastAPI CRM.



  When to Use This CLAUDE.md Template


  
    - Starting a new CRM project with Angular Material on the frontend and FastAPI on the backend.

    - Seeking a consistent CLAUDE Code block that defines API contracts, models, and deployment rules.

    - Creating a reusable project structure with tests and CI guidance for this stack.

    - Ensuring strong separation of concerns and type-safe boundaries between frontend and backend services.

  

  Copyable CLAUDE.md Template


  Paste this directly into a CLAUDE.md file. It includes roles, architecture rules, and concrete guardrails for the Angular Material + FastAPI CRM stack.


  # CLAUDE.md

Project role: You are Claude Code. Your task is to generate a starter CLAUDE Code block for a full-stack CRM using Angular Material on the frontend and FastAPI on the backend. Produce concrete, runnable instructions that guide developers from project setup to deployment.

Architecture rules:
- Use a clean, layered architecture: frontend (Angular Material) and backend (FastAPI) communicate via JSON REST API with well-defined Pydantic models. API contracts must be explicit and versioned.
- Backend uses PostgreSQL with Alembic migrations. Frontend consumes JSON schemas and DTOs generated from the backend where possible.
- Authentication uses JWT Bearer tokens stored in httpOnly cookies. Backend issues access and refresh tokens; refresh tokens rotate.
- Protect API endpoints with role-based access control (RBAC) for a CRM: admins, sales reps, and readers. Enforce authorization at the router layer.
- Use openapi-driven endpoints with clear response shapes and error handling.
- Do not hard-code secrets; pull credentials and config from environment variables.
- All code must be lintable, type-checked, and documented in-line where practical.

File structure rules:
- Root contains frontend/ and backend/ directories. Each stack-specific module must be isolated.
- frontend/ contains angular.json, package.json, src/app, and assets. Backend/ contains main.py, api/, models/, schemas/, core/, db/, and tests/.
- Use conventional naming: kebab-case for folders, PascalCase for class names, snake_case for Python modules.
- Include a docker-compose.yml that builds both frontend and backend images and runs migrations on startup.

Authentication rules:
- JWT-based authentication with access and refresh tokens.
- Tokens are issued at login, stored in httpOnly cookies on the client, and rotated on refresh.
- Passwords are hashed with bcrypt; never log plaintext passwords.
- Protect endpoints with OAuth2 scopes and RBAC annotations in FastAPI.

Database rules:
- PostgreSQL as the primary data store.
- Use SQLAlchemy for ORM and Alembic for migrations.
- Define models for User, Lead, Contact, Company, Deal, and Activity with appropriate relationships.
- Use database migrations in CI/CD to ensure schema versioning.

Validation rules:
- Use Pydantic models on the backend for all request/response payloads.
- Validate all inputs server-side; never rely on client-side validation alone.
- Frontend forms map to TypeScript interfaces that reflect backend DTOs.

Security rules:
- Use TLS for all network traffic; enforce secure cookies and proper CORS settings.
- Do not expose secrets in the repository or error messages.
- Avoid expensive queries on hot paths; implement pagination and query limits to prevent DoS.
- Apply input sanitization to prevent injection and XSS in UI bindings.

Testing rules:
- Backend: unit tests for models, validators, and API endpoints using pytest.
- Frontend: unit tests for Angular components and services; end-to-end tests where feasible with Playwright.
- CI runs tests on push; ensure fast feedback loops.

Deployment rules:
- Provide a Dockerfile for frontend and backend, and a docker-compose.yml for local dev.
- Use environment-specific config with 12-factor principles; avoid embedding secrets.
- Migrations run automatically on startup in development; in production, run migrations as a separate step in CI/CD.

Things Claude must not do:
- Do not generate insecure authentication flows or store tokens insecurely.
- Do not bypass backend RBAC checks or assume all requests are authorized.
- Do not embed secrets or credentials in the CLAUDE.md block.
- Do not propose using deprecated Angular Material components or outdated FastAPI features.



  Recommended Project Structure


  Stack-specific directory tree for Angular Material + FastAPI CRM starter.


  frontend/
  angular.json
  package.json
  tsconfig.json
  src/
    app/
      core/
      features/
        crm/
      app.module.ts
      app.component.ts
  assets/
  styles.css

backend/
  app/
    main.py
    api/
      routers/
      v1/
        crm.py
    models/
    schemas/
    core/
    db/
    services/
  alembic/
  tests/
  requirements.txt
  Dockerfile
  docker-compose.yml
  alembic.ini


  Core Engineering Principles


  
    - Type-safe contracts between frontend and backend via explicit DTOs and Pydantic models.

    - Clear separation of concerns: independent frontend and backend modules with stable API surfaces.

    - Repeatable builds and migrations; CI should reproduce production conditions locally.

    - Accessibility and responsive UI with Angular Material components.

    - Security-by-default: secure authentication, proper CORS, and safe data handling.

  

  Code Construction Rules


  
    - Frontend: Angular Material components wired to a CRM domain model; service layer communicates with FastAPI via REST endpoints.

    - Backend: FastAPI app with routers for Users, Leads, Contacts, Companies, and Deals; use Pydantic schemas for requests/responses.

    - Use SQLAlchemy ORM with Alembic migrations; create seed scripts for initial CRM data.

    - Endpoints must be documented in OpenAPI; responses must follow predefined DTOs.

    - Validation should occur on both client and server; provide meaningful error messages.

  

  Security and Production Rules


  
    - Use TLS; store JWTs in httpOnly cookies; implement rotating refresh tokens.

    - RBAC enforcements on all sensitive endpoints; avoid privilege escalation paths.

    - Limit data exposure; only return necessary fields in API responses.

    - Audit logging for authentication events without logging PII in plaintext.

  

  Testing Checklist


  
    - Unit tests for backend models, validators, and API endpoints; mocks for external services.

    - Integration tests for API routes and data layer; end-to-end tests for essential CRM flows.

    - Frontend tests for core components and services; ensure Material theming and responsiveness.

    - CI/CD: run tests on push; verify migrations and builds succeed.

  

  Common Mistakes to Avoid


  
    - Assuming client-side validation is sufficient; always validate on the server.

    - Hard-coding secrets or credentials in code or CLAUDE.md templates.

    - Ignoring RBAC; expose endpoints to all authenticated users.

    - Using deprecated dependencies or outdated Angular/FastAPI patterns.

  

  FAQ


  
    What is the purpose of this CLAUDE.md Template?
    It provides a copyable CLAUDE Code block and a full-stack starter for an Angular Material + FastAPI CRM, including architecture, files, and deployment guidance.
    Which stack does this template target?
    Frontend: Angular Material; Backend: FastAPI; Database: PostgreSQL; Authentication: JWT in httpOnly cookies.
    Where should I place the CLAUDE.md file?
    Place the CLAUDE.md at the root of your project or alongside the related CLUDE.md Template page for consistency.
    How are API contracts defined?
    API contracts are defined via Pydantic models on the backend and mirrored DTOs on the frontend; OpenAPI docs reflect these contracts.
    How do I run migrations in development?
    Use Alembic to run migrations locally via the provided docker-compose or a local script as part of startup.