CLAUDE.md Template: Angular Material + Flask REST API Starter

Overview

This CLAUDE.md Template describes a starter for a typical modern web app that combines an Angular Material frontend with a Flask REST API backend. It is a copyable CLAUDE.md template designed for Claude Code to scaffold a secure, API-first project structure with clear separation of concerns.

Direct answer: You get a ready-to-paste CLAUDE.md block plus an explicit stack-aware project layout, security rules, testing checks, and deployment guidance tailored to Angular Material + Flask REST API.

When to Use This CLAUDE.md Template

• You need a quick, opinionated starter that pairs Angular Material UI with a Flask REST API backend.
• You're implementing a dashboard or admin panel with role-based authentication and API security concerns.
• You want a consistent, copy-paste CLAUDE.md to standardize CLAUDE Code usage across teams.

Copyable CLAUDE.md Template

# CLAUDE.md

Project role
- You are Claude, a code generation assistant tasked with delivering a production-ready CLAUDE.md template for an Angular Material frontend and Flask REST API backend.

Architecture rules
- Build a clear separation between frontend (Angular Material) and backend (Flask REST API).
- Endpoints under /api/v1 are versioned and RESTful.
- Use CORS with allows a controlled origin list; never expose the API publicly without auth.
- JWT-based authentication with short expiry and refresh tokens; store tokens securely.
- Backend services should be stateless; store state in a database, not in memory.
- All responses follow a consistent JSON shape with status and data fields.

File structure rules
- backend/
  - app.py
  - config.py
  - models.py
  - routes/
  - services/
  - extensions.py
  - migrations/
- frontend/
  - angular.json
  - package.json
  - src/
    - app/
      - modules/
      - components/
      - services/
- docker-compose.yml and Dockerfiles for both services.

Authentication rules
- POST /api/v1/auth/login with email/password returns a JWT.
- Use Authorization: Bearer  for protected routes.
- Implement token refresh flow at /api/v1/auth/refresh.
- Do not expose password hashes or secrets in API responses.

Database rules
- Use PostgreSQL via SQLAlchemy; migrations via Alembic.
- Enforce unique email fields and proper indexed foreign keys.
- Do not store plaintext passwords; hash correctly with a strong algorithm (bcrypt).

Validation rules
- Validate all inputs with Marshmallow schemas; reject invalid payloads with 400.
- Return precise error messages without leaking internal details.
- Validate JWT claims on protected routes.

Security rules
- Use HTTPS in production; set secure, HttpOnly cookies if using cookies.
- Disable CSRF for API endpoints; enable CSRF protection for forms in Angular app if needed.
- Implement rate limiting and input sanitization to prevent injection attacks.
- Avoid hard-coded secrets in code; rely on environment variables.

Testing rules
- Backend: unit tests for models, schemas, and routes using pytest.
- Frontend: unit tests with Angular/Jasmine and e2e tests with Cypress.
- Include integration tests for the Flask API and Angular service calls.
- Run tests as part of CI and ensure test data is isolated.

Deployment rules
- Use docker-compose to run backend and frontend in local dev; production uses Kubernetes or a cloud run environment.
- Gunicorn as the Flask WSGI server; Nginx as a reverse proxy.
- Use environment-based config; never hard-code endpoints.

Things Claude must not do
- Do not generate code that stores secrets in code or logs.
- Do not assume localhost in a production environment.
- Do not bypass authentication or authorization checks.
- Do not generate insecure endpoints or SQL building strings via string concatenation.
- Do not rely on deprecated libraries; prefer maintained equivalents.

Recommended Project Structure

backend/
  app.py
  config.py
  models.py
  extensions.py
  routes/
    __init__.py
    api.py
  services/
  migrations/

frontend/
  angular.json
  package.json
  tsconfig.json
  src/
    app/
      modules/
      components/
      services/
  - Dockerfile

docker-compose.yml

Core Engineering Principles

• Explicit API contracts between frontend and backend; consistent data schemas.
• Strong separation of concerns: UI concerns in Angular, data access in Flask.
• Security by default: proper authentication, input validation, and secure headers.
• Testable by design: unit/integration tests for both frontend and backend.
• Maintainable and scalable: modular code, clear naming, and versioned APIs.

Code Construction Rules

• Backend: Flask with blueprints, SQLAlchemy, Marshmallow, and JWT for auth.
• Frontend: Angular Material components with a clean service layer for API calls.
• API routes under /api/v1 with explicit versioning.
• Use environment variables for config; no hard-coded values.
• Follow consistent naming conventions for files, routes, and models.

Security and Production Rules

• Enable TLS in production and configure secure cookies when using cookies.
• Validate all inputs; never trust client-side validation alone.
• Implement rate limiting and proper CORS configuration.
• Use parameterized queries to prevent SQL injection; avoid dynamic SQL assembly.

Testing Checklist

• Unit tests for Flask models, schemas, and API endpoints.
• Integration tests for end-to-end API calls from Angular service layer.
• Frontend unit tests for Angular components and services.
• CI pipeline runs tests and linting on push/PR.
• Manual smoke tests for happy-path API usage and error handling.

Common Mistakes to Avoid

• Hard-coding secrets or credentials in code or config files.
• Overly permissive CORS or unauthenticated API endpoints in prod.
• Skipping input validation or trusting client-side validation only.
• Not validating JWT claims or leaking token information in responses.

FAQ

Q1: What is this CLAUDE.md Template for?

A: It provides a copyable CLAUDE.md template for an Angular Material frontend paired with a Flask REST API backend, including auth, validation, and deployment guidance.

Q2: Which stack does this template cover?

A: Angular Material on the frontend and Flask REST API on the backend with PostgreSQL, JWT, and Marshmallow validation.

Q3: How do I start using the template?

A: Paste the CLAUDE.md block into Claude Code, then adapt endpoints, models, and UI according to your project specifics.

Q4: What security considerations are included?

A: JWT authentication, proper API scoping, CSRF considerations for APIs, TLS guidance, and secure config handling.

Q5: How do I test and deploy?

A: Use pytest for Flask, Angular tests for the frontend, and Docker Compose for local deployment; prepare Gunicorn and Nginx for prod.