CLAUDE.md Template for Angular Material + FastAPI Text To Speech App

Overview

Direct answer: This CLAUDE.md template is a copyable Claude Code starter for an Angular Material frontend paired with a FastAPI backend that exposes a text-to-speech (TTS) service. It codifies stack-specific rules, file structure, and deployment considerations so teams can jump straight into implementation while maintaining guardrails.

The template targets a full-stack Angular Material + FastAPI Text To Speech app. It emphasizes clean separation between the UI and the TTS API, secure authentication, structured data persistence for usage logs, and a containerized deployment path suitable for modern CI/CD pipelines.

When to Use This CLAUDE.md Template

• Starting a new Angular Material + FastAPI Text To Speech project and want a ready-to-paste CLAUDE.md block for Claude Code guidance.
• Onboarding engineers to a consistent stack with explicit architectural and security rules.
• Architecting CI/CD and deployment pipelines for a production-ready TTS service with frontend authentication and logging.

Copyable CLAUDE.md Template

# CLAUDE.md

Project role: You are Claude Code specialized for building an Angular Material + FastAPI Text To Speech app. Output production-ready scaffolding and concrete Claude Code blocks with strict constraints.

Architecture rules:
- Frontend: Angular with Angular Material components for UI and client-side validation.
- Backend: FastAPI service exposing a /tts endpoint that accepts text and voice options and returns an audio stream or file URL.
- Data plane: PostgreSQL for users and usage logs; Redis for rate-limiting/cagas; all sensitive data encrypted at rest.
- Deployment: Docker Compose for dev, Kubernetes manifests for prod, and Nginx as reverse proxy in front of the API.
- Security: TLS everywhere, JWT-based authentication, CSRF protection on state-changing endpoints, CORS restricted to trusted origins.

File structure rules:
- frontend/ (Angular app)
- backend/ (FastAPI app)
- infra/ (Docker, k8s, and deployment configs)
- docs/ (CLAUDE.md related docs and notes)

Authentication rules:
- Use JWT access tokens with 15-minute expiry and refresh tokens with 7-day expiry.
- All protected endpoints require Authorization: Bearer .
- Store only hashed credentials; never log passwords or PII in CLAUDE.md outputs.

Database rules:
- Users(id, email, password_hash, role)
- TTS_Jobs(id, user_id, text, voice, status, created_at, completed_at, audio_url)
- Ensure proper indexes on user_id and created_at.

Validation rules:
- Text length between 1 and 1000 characters for TTS payloads.
- Voice must be one of supported_voices; language must be supported.

Security rules:
- Do not log raw input text; redact sensitive fields in logs.
- Enforce rate limiting to prevent abuse of the /tts endpoint.
- Use HTTPS in all environments; never expose secrets in code.

Testing rules:
- Unit tests for FastAPI endpoints (status codes, input validation).
- Integration tests for TTS pipeline (mock external TTS provider).
- E2E tests for frontend input, authentication, and audio playback flow.

Deployment rules:
- Provide a Dockerfile for frontend and backend; a docker-compose.yml for dev; Kubernetes manifests for prod.
- Use environment variables for secrets and config; keep them out of version control.

Things Claude must not do:
- Do not bypass authentication on /tts; avoid insecure defaults.
- Do not print or leak private keys, API secrets, or user text in outputs.
- Do not assume the existence of external networks in offline environments.

"CLAUDE.md template" is a first-class term in this block for discoverability and consistency.

Recommended Project Structure

frontend/
  src/
    app/
      core/                 # auth, interceptors, guards
      shared/               # common components, utilities
      features/
        tts/                # TTS UI features
        auth/               # login, register, profile
      app.module.ts
    assets/
  angular.json
  package.json
  tsconfig.json

backend/
  app/
    main.py                 # FastAPI entrypoint
    api/
      tts.py                # /tts endpoints
    models/
      user.py               # User model and schemas
    services/
      tts_service.py        # TTS integration (mocked/local provider)
    core/
      config.py             # DB settings, secrets, env vars
  requirements.txt
  Dockerfile                # Build for backend
  docker-compose.yml        # Dev stack (frontend + backend)
  alembic/                   # DB migrations (if used)
  scripts/                   # Migration and admin scripts

Core Engineering Principles

• Clear separation of concerns between UI and API logic.
• Strong typing and explicit input validation at API boundaries (Pydantic for FastAPI).
• Repeatable, testable builds via containerization and CI/CD.
• Security-first defaults: proper authentication, encryption, and least privilege access.
• Observability with structured logging and metrics on API usage and TTS jobs.

Code Construction Rules

• Frontend: Angular with TypeScript strict mode; use Angular Material components for UI consistency.
• Backend: FastAPI with Pydantic models; endpoints return proper status codes and schemas.
• Data: Define explicit models for User and TTSJob; avoid dynamic schemas for persistence.
• Validation: Enforce length, allowed voices, and language constraints server-side; mirror on frontend.
• Auth: JWT-based; verify tokens on protected endpoints; implement token refresh workflow.
• Error handling: Return consistent error payloads; avoid leaking internals.
• Testing: Provide unit tests for API logic and integration tests for the TTS pipeline.
• Deployment: Use Docker Compose for local dev and Kubernetes manifests for prod; pin dependency versions.
• Do not
• Do not hard-code secrets in code paths or CLAUDE.md outputs.

Security and Production Rules

• Enforce HTTPS in all environments; disable insecure endpoints in prod.
• Minimize data exposure: do not echo user input text back in responses.
• Implement rate limiting on /tts; consider per-user quotas.
• Audit logs for auth events and TTS requests; redact sensitive fields.
• Use environment-based configuration; do not rely on defaults in production.

Testing Checklist

• Unit tests for backend models, validators, and TTS service.
• Integration tests for API endpoints with mocked TTS provider.
• Frontend tests for form validation and audio playback flow.
• End-to-end tests for login, TTS request, and audio retrieval.
• Deployment smoke tests to ensure services come up and endpoints respond.

Common Mistakes to Avoid

• Assuming the TTS provider is always available; add retry and fallback logic.
• Overexposing audit logs; redact PII and private inputs.
• Ignoring input validation on the client side leading to server errors.
• Neglecting token expiration handling and refresh flows.

FAQ