CLAUDE.md Template: Angular Material + Sanic API Starter

Overview

The CLAUDE.md template is a copyable Claude Code blueprint crafted for a stack that combines an Angular Material frontend with a Sanic API backend. It provides a concrete, paste-ready instruction block that guides a developer through architecture, project layout, authentication, data validation, security, testing, and deployment for this stack. This page is a CLAUDE.md template, not a generic boilerplate.

Direct answer: Use this CLAUDE.md Template to generate a stack-consistent Claude Code block for an Angular Material + Sanic API project, ensuring consistent structure, security, and deployment patterns.

When to Use This CLAUDE.md Template

• You are starting a new SPA with Angular Material and need a repeatable Claude Code layout for the frontend and Sanic backend.
• You want an architecture that cleanly separates UI and API concerns with JWT-based auth.
• You require a standardized file structure, testing, and deployment rules that are easy to copy into CLAUDE Code sessions.
• You are documenting best practices for developers adopting Claude Code workflows in this stack.

Copyable CLAUDE.md Template

# CLAUDE.md

Project role: Frontend-Backend Architect (Angular Material + Sanic API)

Architecture rules:
- Separate monorepo with two apps: frontend (Angular Material) and server (Sanic API).
- Client and server communicate via REST over HTTPS; use JWT Bearer tokens for auth.
- Backend uses PostgreSQL; ORM layer optional (SQLAlchemy) with async support if possible.
- All environment-specific config loaded from environment variables; do not hard-code secrets.
- No server-side rendering; the frontend is a standalone SPA.

File structure rules:
- frontend/
  - src/
    - app/
      - components/
      - services/
      - models/
  - angular.json
  - package.json
  - tsconfig.json
- server/
  - app.py
  - requirements.txt
  - models/
  - routes/
  - config/
- docker-compose.yml
- docker/
  - frontend.Dockerfile
  - backend.Dockerfile

Authentication rules:
- Use JWT issued by the Sanic API; pass tokens via Authorization: Bearer  header.
- Refresh tokens managed server-side with short-lived access tokens.
- Do not store JWTs in localStorage; prefer httpOnly cookies when feasible; otherwise use secure storage with explicit expiry.
- Implement login, refresh, and logout endpoints.

Database rules:
- PostgreSQL as the primary database for server data.
- Use async database access when possible; validate inputs to prevent SQL injection.
- Do not embed plain credentials in source code; load from environment variables.

Validation rules:
- Server: Validate all request payloads against pydantic-like models or equivalent schemas.
- Frontend: Use Angular reactive forms with proper validators for required fields, formats, and length.

Security rules:
- Enforce HTTPS in all environments; disable debug endpoints in production.
- Use CSRF protection for cookie-based flows; otherwise rely on Authorization header security.
- Limit CORS to known origins; implement rate limiting on API endpoints.
- Hash passwords with a strong algorithm (e.g., bcrypt) and store only salted hashes.

Testing rules:
- Backend: unit tests with pytest; integration tests for critical endpoints using httpx/pytest.
- Frontend: unit and component tests with Jasmine/Karma; end-to-end tests with Cypress where applicable.
- Include test data fixtures and seed scripts in server/tests/fixtures.

Deployment rules:
- Docker Compose setup with frontend, Sanic backend, and PostgreSQL; include migrations and seed scripts.
- Use environment variables for secrets; mount config files securely.
- Run linting and tests in CI before deployment.

Things Claude must not do:
- Do not bypass authentication or return 200 on unauthorized requests.
- Do not rely on insecure defaults or embed secrets in code.
- Do not generate or imply usage of unsupported libraries for this stack (no Prisma, no Mongoose).
- Do not assume SSR or server-side rendering for the Angular app.

Recommended Project Structure

frontend/
  angular.json
  package.json
  tsconfig.json
  src/
    main.ts
    index.html
    assets/
    styles.css
    app/
      app.module.ts
      app-routing.module.ts
      components/
      services/
      models/
      shared/
  environments/
    environment.ts
    environment.prod.ts
server/
  app.py
  requirements.txt
  config/
    config.py
  models/
    user.py
  routes/
    auth.py
    items.py
  migrations/
  tests/
    test_auth.py
    test_items.py
  utils/
    database.py
docker-compose.yml
docker/frontend.Dockerfile
docker/backend.Dockerfile
README.md

Core Engineering Principles

• Clear separation of concerns between UI (Angular Material) and API (Sanic).
• Explicit contract-driven design with typed data models for both frontend and backend.
• Security by design: JWT-based auth, HTTPS, proper CORS, and secret management.
• Deterministic structure and naming conventions for faster onboarding.
• Testability: unit, integration, and CI-friendly tests for both layers.

Code Construction Rules

• Frontend should use Angular with strict mode, AOT compilation, and Angular Material components only.
• Backend endpoints must be async-friendly; Sanic should expose clear REST routes with input validation.
• Use environment variables for all secrets; never hard-code credentials.
• Define API schemas (request/response) in a single source of truth and reuse in tests.
• Maintain a minimal public API surface; document all endpoints with proper typing.
• Do not add unnecessary libraries; keep dependencies aligned with the stack.

Security and Production Rules

• JWT tokens with short lifetimes; refresh tokens handled server-side.
• HTTPS enforced; disable debug tooling in production.
• CORS restricted to the frontend origin; rate limiting on sensitive endpoints.
• Secret rotation and secure storage for credentials and API keys.
• Input validation and output encoding to prevent injection attacks.

Testing Checklist

• Backend: unit tests for models and utilities; integration tests for auth and data endpoints.
• Frontend: unit tests for components and services; accessibility checks for Angular Material UI.
• CI: lint, type-check, unit tests, and end-to-end tests on every PR.
• Deployment: smoke tests for containerized services after deployment.

Common Mistakes to Avoid

• Mixing frontend and backend concerns in a single folder; keep clear boundaries.
• Storing secrets in code or public repos; always use environment variables.
• Weak input validation or bypassing authentication checks.
• Over-fetching data or missing pagination in API responses.

FAQ

• What is this CLAUDE.md Template? A copyable Claude Code blueprint for an Angular Material + Sanic API stack.
• Which stack does this template target? Angular Material frontend with a Sanic Python API backend using PostgreSQL.
• How do I use the copyable Claude Code block? Paste the block into a CLAUDE.md file and follow the project role, rules, and deployment guidance.
• What testing should I perform? Unit and integration tests for backend; unit, component, and E2E tests for frontend; CI integration.
• How is authentication handled? JWT Bearer tokens with refresh flow; tokens passed in Authorization header.

Notes

This page is a CLAUDE.md Template page intended to be copy-paste ready for Claude Code workflows. It is stack-specific and focused on Angular Material + Sanic API projects.