CLAUDE.md Template: Angular Material + Tornado API

Overview

This CLAUDE.md template provides a complete, copyable Claude Code blueprint for a full-stack project using Angular Material for the frontend and Tornado for the API backend. It’s designed so you can paste the included CLAUDE.md block into Claude Code and quickly generate a consistent, production-ready starter for this stack.

Direct answer: This template yields a reproducible CLAUDE.md block that encodes architecture, file layout, and implementation constraints for Angular Material + Tornado API.

When to Use This CLAUDE.md Template

• You’re starting a new Angular Material + Tornado API project and want a consistent CLAUDE.md blueprint.
• You need stack-specific constraints to guide Claude Code, including file structure and security rules.
• You require a clearly defined recommended project structure to prevent architecture drift.
• You want a reusable, copyable template to onboard new engineers quickly.

Copyable CLAUDE.md Template

# CLAUDE.md

Project role:
- You are Claude Code. You act as a blueprint consultant for a full-stack Angular Material frontend and Tornado API backend. Deliver precise, actionable steps and outputs that can be pasted directly into a CLAUDE.md file.

Architecture rules:
- Frontend: Angular (v16+), TypeScript, Angular Material components; responsive UI; strict typing; unit-tested components.
- Backend: Tornado (Python 3.11+), REST endpoints; JWT-based authentication; asynchronous handlers when applicable.
- Data flow: consistent API shapes; use shared TypeScript interfaces for requests/responses; avoid leaky abstractions.

File structure rules:
- Project root contains client/ (Angular) and server/ (Tornado).
- Client should house src/app with components, pages, services; server contains app/ (handlers), models/ (data types), and a main.py to bootstrap the server.

Authentication rules:
- Use JWT with RS256; tokens issued by an auth endpoint; include token validation middleware for protected routes.
- Do not expose refresh tokens to the client in local storage; implement refresh with httpOnly cookies when possible.

Database rules:
- PostgreSQL is recommended; include schema.sql and seed.sql; ensure connections are parameterized and credentials are stored in env vars.

Validation rules:
- Validate all API inputs on the server; return 400 with a descriptive message for invalid payloads.
- Use TypeScript interfaces on the client and Python type hints on the server sides.

Security rules:
- Enforce HTTPS; set CORS with a tight policy (origins limited to your domaines); disable debug endpoints in production.
- Do not hard-code secrets; use environment-based configuration.

Testing rules:
- Client: unit tests for components and services; minimal end-to-end tests for critical flows.
- Server: unit tests for handlers and validators; integration tests for API endpoints using pytest.

Deployment rules:
- Provide a Dockerfile for the frontend and backend, and a docker-compose.yml for dev; outline Kubernetes manifests for production.
- Automate migrations with a bootstrap script in server/ migrations if a DB is used.

Things Claude must not do:
- Do not generate or embed secrets; Do not recommend insecure default credentials; Do not assume a global database without explicit config; Do not bypass authentication or authorization checks.

Recommended Project Structure

client/
  angular.json
  package.json
  tsconfig.json
  src/
    app/
      components/
      pages/
      services/
  assets/
  styles.css
server/
  tornadoapp/
    handlers/
    models/
  main.py
requirements.txt
.env.example
docker-compose.yml

Core Engineering Principles

• Separation of concerns between frontend and backend with clear API contracts.
• Security-first design: proper authentication, authorization, and input validation.
• Type safety across TypeScript and Python with explicit interfaces and hints.
• Reproducible builds and deploys using Docker and minimal environment-specific logic.
• Deterministic naming and folder structures to reduce onboarding friction.

Code Construction Rules

• Frontend must use Angular Material components with a consistent theming system.
• API payloads must have defined TypeScript interfaces and Python type hints; avoid any.
• HTTP client usage should be centralized in services with typed responses and error handling.
• Backend handlers must validate input and return structured error messages with appropriate HTTP status codes.
• Do not couple frontend directly to internal server models; use DTOs for requests/responses.

Security and Production Rules

• Enforce TLS in all environments; configure reverse proxy with TLS termination.
• CORS policy must be explicit; avoid wildcards.
• Store secrets as environment variables; rotate credentials regularly.
• Audit logs for authentication attempts and API access; avoid logging sensitive payload data.

Testing Checklist

• Unit tests for Angular components and services; mock HTTP responses for deterministic tests.
• API integration tests for Tornado endpoints; verify authentication flows and error handling.
• End-to-end checks for a typical user scenario (login, fetch data, logout).
• Deployment smoke tests to ensure containers start correctly and services communicate.

Common Mistakes to Avoid

• Assuming a particular database schema without explicit config; failing to mirror production data shape in tests.
• Over-tight coupling between client and server models; not using DTOs as a buffer.
• Neglecting error handling and logging in API endpoints.
• Forgetting to secure secrets and credentials; leaking sample tokens in code.

FAQ

Q1: What is a CLAUDE.md Template?

A1: A copyable Claude Code blueprint that encodes stack-specific constraints for rapid, consistent CLAUDE.md generation.

Q2: Which stack is covered by this template?

A2: Angular Material frontend with a Tornado API backend.

Q3: How should I use this template?

A3: Copy the CLAUDE.md block into your CLAUDE.md file and adapt project specifics (URLs, tokens, DB configs) as needed.

Q4: What deployment approaches are recommended?

A4: Use Docker Compose for development and Kubernetes manifests for production, with environment variables and migrations as needed.

Q5: What should Claude avoid here?

A5: Do not generate secrets, rely on insecure defaults, or assume a global database without explicit config.