Angular Material + Falcon API CLAUDE.md Template

Overview

Direct answer: This CLAUDE.md template provides a copyable Claude Code block to scaffold a full-stack Angular Material frontend with a Falcon API backend, including authentication, API design, validation, and deployment guidelines.

The stack covered by this template includes an Angular Material-based user interface that consumes a Falcon-based Python API. It enforces a clean separation between frontend and backend, uses JWT for authentication, and targets PostgreSQL as the database in a production-ready setup. Use this to produce a reproducible CLAUDE.md file you can paste into Claude Code and customize for your project.

When to Use This CLAUDE.md Template

• Starting a project with an Angular Material frontend and a Falcon backend where you want a ready-to-paste CLAUDE.md block.
• Enforcing a consistent architecture for frontend-backend integration and CI/CD readiness.
• Documenting the expected file structure, auth flow, API contracts, and deployment steps from day one.
• Educating team members on stack-specific best practices for security, validation, and testing.

Copyable CLAUDE.md Template

# CLAUDE.md
Project role: Full-stack engineer for Angular Material frontend + Falcon API backend
Architecture rules:
- Separate frontend and backend into distinct folders with explicit contracts (API surface).
- Use JWT-based authentication with access/refresh tokens; backend validates tokens on every protected route.
- Frontend should communicate with the Falcon API via a single /api base path; avoid direct backend calls from UI services.
- All API responses must be normalized to a consistent shape with status and data fields.
- Use a strict Content Security Policy (CSP) and TLS; enable HTTP Strict Transport Security (HSTS).

File structure rules:
- frontend/ (Angular Material app)
  - src/app/ (components, pages, services)
  - angular.json, package.json, tsconfig.json
- backend/ (Falcon API)
  - app/ (resources, middleware, auth)
  - main.py
  - requirements.txt
- scripts/ (seed/setup scripts)
- tests/ (frontend & backend tests)

Authentication rules:
- JWT-based authentication using HS256 if possible; tokens issued by Falcon auth service.
- Do not store tokens in localStorage; prefer HttpOnly cookies for web clients when feasible, or secure storage with proper rotation.
- Protect all sensitive endpoints with proper scope/role checks.

Database rules:
- Use PostgreSQL in production; SQLAlchemy as ORM or raw SQL with careful migrations.
- Do not rely on SQLite for production; use migrations for schema changes.
- Validate inputs at the database boundary; apply constraints and indexing for performance.

Validation rules:
- Validate all incoming payloads against explicit schemas (Marshmallow or Pydantic-based schemas for Falcon).
- Return structured validation errors with field-level messages.

Security rules:
- Enforce CSRF protection for state-changing requests if cookies are used; otherwise rely on stateless JWT.
- Treat all secrets as environment variables; avoid hardcoding.
- Implement rate limiting on API endpoints; monitor for abuse.

Testing rules:
- Frontend: Unit tests (Jest or Angular TestBed) and integration tests for Material components.
- Backend: Pytest-based tests for Falcon resources and middleware; use Falcon test client for route tests.
- CI should run unit tests, linting, and a basic integration test of frontend-backend interaction.

Deployment rules:
- Docker Compose or Kubernetes deployment for frontend and backend together.
- Use docker-compose up to run both services in development; ensure environment variables for DB connection and JWT keys.
- Health check endpoints for API and a simple UI smoke test after deployment.

Things Claude must not do:
- Do not generate insecure token handling or expose secrets in code blocks.
- Do not assume a specific cloud provider; keep deployment blocks provider-agnostic where possible.
- Do not hardcode database credentials or API keys.

Recommended Project Structure

frontend/
  angular.json
  package.json
  tsconfig.json
  src/
    app/
      components/
        - material/ (Angular Material components)
        - shared/ (shared components)
      app.module.ts
      app-routing.module.ts
      environments/
backend/
  app/
    __init__.py
    resources/
      auth.py
      items.py
  main.py
  requirements.txt
  Dockerfile
  .env.example
scripts/
  seed.py
tests/
  frontend/
  backend/

Core Engineering Principles

• Clear separation of concerns: distinct frontend and backend layers with a defined API surface.
• Explicit contracts: stable API schemas and predictable data shapes for all responses.
• Security by default: JWT auth, CSP, TLS, and safe token storage practices.
• Testability: unit, integration, and end-to-end tests wired into CI.
• Reproducibility: Dockerized/runbook-ready templates and deterministic file structure.

Code Construction Rules

• Frontend must use Angular Material components with a consistent theming strategy.
• Backend endpoints under /api must be authenticated and validated.
• Define Marshmallow/Pydantic-like schemas for request validation in Falcon resources.
• Use SQLAlchemy for database access with clear models and migrations.
• Ensure all responses are JSON with { status, data } shapes and proper error codes.
• Documentation-like CLAUDE.md content must be copyable and pasteable as-is.
• Do not rely on deprecated libraries; pin versions and specify compatibility.

Security and Production Rules

• Use environment variables for secrets; never commit keys.
• Enable HTTPS/TLS in all environments; enable HSTS in production.
• Implement token expiration and rotation; short-lived access tokens with refresh tokens.
• Validate inputs and sanitize all outputs to prevent injection attacks.
• Apply rate limiting and logging/monitoring for anomaly detection.

Testing Checklist

• Frontend unit tests for Material components; run npm test or ng test.
• Backend unit tests for Falcon resources and middleware; run pytest.
• Integration tests to verify API contracts between Angular frontend and Falcon API.
• Deployment checks: build Docker images, run containers, and verify health endpoints.

Common Mistakes to Avoid

• Coupling frontend directly to internal backend implementation details; keep a stable API surface.
• Storing tokens in insecure storage or not rotating secrets.
• Skipping validation: trust no input; validate at API boundary first.
• Over-optimizing for one stack at the expense of cross-stack clarity (avoid useless abstractions).

FAQ

What is the purpose of this CLAUDE.md Template?

Provides a copyable CLAUDE.md block for building an Angular Material frontend with a Falcon API backend.

What stack does this template cover?

Angular Material for the frontend and Falcon (Python) for the API backend, with PostgreSQL as the database.

Which authentication approach is recommended?

JWT-based authentication with access and refresh tokens managed by the Falcon API.

How should I test this stack?

Unit tests for frontend and backend, integration tests for API endpoints, and deployment checks.

Where can I customize the project structure?

Follow the Recommended Project Structure and adjust the file tree to suit your project.