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

Overview

The CLAUDE.md template provides a copyable Claude Code starter tailored for a full-stack Angular Material frontend with a FastAPI backend that performs speech-to-text processing. It outlines stack-specific conventions, file structure, security rules, testing, and deployment guidance so developers can paste the included CLAUDE.md block directly into their project.

Direct answer: It gives you a ready-to-paste Claude Code prompt and rules that enforce Angular Material UI, FastAPI endpoints, and speech-to-text processing with clear constraints and checks for production readiness.

When to Use This CLAUDE.md Template

• You are building a web app with an Angular Material UI and a FastAPI backend that transcribes audio to text.
• You want a copyable Claude Code block to accelerate development and enforce best practices from day one.
• You need concrete rules for file layout, authentication, data validation, and deployment tailored to this stack.

Copyable CLAUDE.md Template

# CLAUDE.md

Project Role: Full-Stack Engineer for Angular Material + FastAPI Speech-To-Text App

Architecture Rules:
- Use Angular 17+ with Angular Material for UI; FastAPI backend in Python 3.11+
- Speech-to-text processing via Whisper on the backend (or a supported cloud service)
- RESTful APIs with well-defined Pydantic schemas; asynchronous endpoints where appropriate
- Separate frontend and backend deployment; use a reverse proxy and environment-based config
- Use PostgreSQL as the data store with SQLAlchemy ORM and Alembic migrations

File Structure Rules:
- frontend/ contains the Angular Material project (src/app, assets, environments)
- backend/ contains FastAPI project (main.py, app/, models/, routers/, services/)
- shared/ contains common types and utilities used by both sides
- config/ contains environment configuration and secrets management templates

Authentication Rules:
- OAuth2PasswordBearer with JWT tokens; refresh tokens implemented via /auth/refresh
- Store tokens securely (httpOnly cookies preferred) in the frontend; avoid localStorage for tokens
- Protect endpoints with scopes and roles; implement token revocation when needed

Database Rules:
- PostgreSQL with SQLAlchemy ORM; use Alembic for migrations
- Enforce DB constraints, indexes on transcripts and user data; use parameterized queries
- Do not log raw audio data in plaintext; watermark or redact sensitive content if stored

Validation Rules:
- Use Pydantic models for request/response validation; validate audio payload formats (base64 or binary)
- Enforce max payload size and rate limits on transcription endpoints

Security Rules:
- Enforce TLS, sane CORS defaults, and CSRF protection for non-RESTful flows
- Validate JWT on protected routes; implement proper error handling for expired tokens
- Never hard-code secrets; rely on environment variables or a secrets manager

Testing Rules:
- Unit tests for validators and utilities; integration tests for /transcribe and /auth endpoints using HTTPX
- End-to-end tests simulating audio upload and transcription pipeline
- Linting and type checks (mypy) in CI; run pytest in CI on push/PR

Deployment Rules:
- Docker Compose for local development; container orchestration via Docker/Kubernetes for prod
- Use multi-stage builds; pin dependencies; run security scans in CI
- Environment-based configuration and secret management; metrics and logging enabled in prod

Things Claude Must Not Do:
- Do not write to local disk in request handlers; use storage services with proper permissions
- Do not bypass authentication or input validation for any endpoint
- Do not assume cloud provider SDKs are always available in business logic
- Do not bypass OpenAPI schemas or loosen type checks

Recommended Project Structure

frontend/
  angular.json
  package.json
  tsconfig.json
  src/
    app/
      components/
        transcription-dashboard/
          transcription-dashboard.component.html
          transcription-dashboard.component.ts
      services/
      app.module.ts
      main.ts
  assets/
  environments/
backend/
  main.py
  requirements.txt
  config.py
  database.py
  app/
    api/
      v1/
        endpoints/
        models/
        routers/
    models/
    routers/
    services/
  alembic/
  Dockerfile

Core Engineering Principles

• Separation of concerns: distinct frontend, backend, and shared types
• Explicit contracts: clear input/output models and endpoint schemas
• Testability: unit, integration, and end-to-end tests with deterministic fixtures
• Security by design: authentication, authorization, input validation, and encryption
• Observability: structured logging, metrics, and health checks

Code Construction Rules

• Frontend must be Angular Material-based with TypeScript strict mode
• Backend must expose REST endpoints for transcription with clear request/response DTOs
• Audio payloads must be validated and sanitized; use streaming or chunked uploads if needed
• Use Pydantic models on FastAPI; typing with TypedDict or dataclasses on frontend
• Endpoint names should be descriptive and versioned (e.g., /api/v1/transcribe)
• Do not couple UI components to backend internals; define stable API contracts

Security and Production Rules

• TLS termination in reverse proxy; disable insecure endpoints in prod
• JWT with short-lived access tokens and refresh flow; store tokens securely
• CSRF protection for state-changing requests; CORS limited to known origins
• Secrets management using environment variables or a dedicated secret store
• Audit logging for transcription activities and access control events

Testing Checklist

• Unit tests for validators, utilities, and model schemas
• Integration tests for /transcribe and authentication flows using HTTPX
• End-to-end tests simulating audio capture and transcription output
• Static analysis (linting) and type checks (mypy) in CI
• Build verification and security scans before deployment

Common Mistakes to Avoid

• Skipping input validation for audio payloads
• Omitting proper authentication on transcription endpoints
• Using localStorage for tokens or secrets in frontend
• Ignoring CORS and TLS in development vs production
• Overloading a single endpoint with heavy processing causing timeouts

FAQ

• Q: What is this CLAUDE.md Template for?
  A: It provides a copyable Claude Code starter for an Angular Material + FastAPI speech-to-text app, with stack-specific rules and deployment guidance.
• Q: Which stack is covered?
  A: Angular Material frontend and FastAPI backend, with Whisper-based speech-to-text processing.
• Q: How do I use the included CLAUDE.md block?
  A: Paste the code block into CLAUDE.md in your project root and follow the architecture and rules specified.
• Q: What should I customize first?
  A: Start with the frontend module for the transcription UI, then implement /transcribe in FastAPI, and wire up the audio capture to the backend.
• Q: How do I deploy?
  A: Use Docker Compose for local dev and a Kubernetes or cloud-run workflow for prod, with separate frontend and backend deployments.