CLAUDE.md Template: Angular Material + FastAPI OCR App

Overview


CLAUDE.md template for Angular Material + FastAPI OCR App provides a compact, copyable Claude Code instruction block that guides you to implement a production-grade OCR workflow. It covers a two-tier stack: an Angular Material frontend and a FastAPI backend that runs OCR using a chosen library. This template is designed for developers who want a ready-to-paste CLAUDE.md block and a stack-specific project layout.


When to Use This CLAUDE.md Template



- You are building a two-tier app with a polished Angular UI and a FastAPI OCR service.

- You want a copy-paste CLAUDE.md instruction block to drive a Claude Code session.

- You need stack-specific file structure guidelines, security rules, and testing checklist.


Copyable CLAUDE.md Template


Copy this CLAUDE.md block into a new file named CLAUDE.md in your project root (or paste into Claude Code):


# CLAUDE.md

Project role: You are Claude Code tasked with generating production-ready code for an Angular Material + FastAPI OCR app. Your outputs must be deterministic and safe for CI.

Architecture rules:
- Maintain a clear frontend-backend boundary: Angular Material SPA communicates with FastAPI REST endpoints.
- Use REST over WebSockets for OCR, unless real-time streaming is essential.
- Do not embed secret keys in the frontend; always fetch tokens from a secure backend or CI secret manager.
- Use a lean OCR model (or a service) with a robust fallback and queueing for bulk work.

File structure rules:
- Frontend: angular-material-fastapi-ocr/frontend/
  - src/app/
    - components/
    - services/
    - models/
  - angular.json
  - package.json
- Backend: angular-material-fastapi-ocr/backend/
  - app/
    - main.py
    - api/
    - models/
    - schemas/
  - requirements.txt
  - Dockerfile

Authentication rules:
- Backend uses OAuth2 with Password (Bearer) tokens or JWTs from a standard provider.
- Frontend stores tokens in memory (not localStorage or cookies) and refreshes tokens via a dedicated endpoint.

Database rules:
- Use a lightweight, typed ORM model in FastAPI if a DB is used; otherwise, use in-memory or file-based storage for OCR results with clear cleanup policies.

Validation rules:
- Validate input images (mime type, size) and reject invalid files immediately.
- Validate OCR results with a schema (required fields, types).

Security rules:
- Enable HTTPS in all environments.
- Validate CORS strictly to the API domains used by the SPA.
- Rate-limit OCR endpoints; harden against large payloads.

Testing rules:
- Unit tests for OCR function wrappers and image preprocessing.
- Integration tests for frontend-backend communication via REST endpoints.
- End-to-end tests for a sample document OCR flow.

Deployment rules:
- Containerize frontend and backend with separate Dockerfiles; orchestrate with docker-compose or Kubernetes.
- Use a public/private key pair for JWTs; rotate keys.

Things Claude must not do:
- Do not write insecure code, bypass validation, or commit secrets.
- Do not assume a specific OCR library beyond what is documented in this CLAUDE.md.
- Do not skip error handling or logging.

Recommended Project Structure


angular-material-fastapi-ocr/
├─ frontend/
│  ├─ src/
│  │  ├─ app/
│  │  │  ├─ components/
│  │  │  ├─ services/
│  │  │  └─ models/
│  │  └─ main.ts
│  ├─ angular.json
│  ├─ package.json
│  └─ tsconfig.json
├─ backend/
│  ├─ app/
│  │  ├─ main.py
│  │  ├─ api/
│  │  │  └─ v1/
│  │  │     └─ ocr.py
│  │  ├─ models/
│  │  ├─ schemas/
│  │  └─ core/
│  │     └─ config.py
│  ├─ requirements.txt
│  ├─ Dockerfile
│  └─ alembic.ini
├─ docker-compose.yml

Core Engineering Principles



- Separation of concerns: clean frontend/backend boundaries and clear API contracts.

- Type-safety: define pydantic models for requests/responses and TypeScript interfaces for frontend data.

- Security by default: follow least privilege, avoid secrets in frontend, enforce HTTPS, and implement basic auth controls.

- Automated tests: unit, integration, and end-to-end checks with minimal flaky tests.


Code Construction Rules



- Frontend: Angular Material components, reactive forms, and lazy-loaded modules.

- Backend: FastAPI endpoints with routers under /api/v1; use Pydantic models for input/output.

- OCR processing should be delegated to a dedicated service function; keep input validation strict.

- Use environment variables for configuration; avoid hard-coded credentials.

- Use Docker multi-stage builds; keep image sizes lean.


Security and Production Rules



- HTTPS mandatory in all environments; disable debug mode in production.

- Configure CORS to allow only known frontend domains.

- Enable policy-based logging and request tracing for OCR requests.

- Limit payload sizes to protect OCR endpoints; implement input validation and error handling.


Testing Checklist



- Unit: OCR wrapper functions, image preprocessing, and data validation.

- Integration: frontend-backend REST calls, token refresh flow, and OCR result formatting.

- End-to-end: sample document OCR flow and UI rendering checks.

- Deployment: build, push to registry, and verify container startup health checks.


Common Mistakes to Avoid



- Over-broad CORS permissions or exposing too much API surface.

- Storing tokens in localStorage; prefer in-memory with proper refresh flow.

- Ignoring input validation or skipping OCR preprocessing steps.

- Neglecting error handling in OCR pipeline or exposing internal error details to clients.


FAQ



What is this CLAUDE.md Template for?
A stack-specific CLAUDE.md template for an Angular Material frontend and a FastAPI OCR backend, with a copyable Claude Code block and a stack-aware project structure.
Which stack does it cover?
Angular Material for the UI and FastAPI for OCR services, with Claude Code guidance tailored to this stack.
How do I use the CLAUDE.md block?
Copy the block into CLAUDE.md at the project root and adapt paths, tokens, and environment details to your setup.
Can I adapt the OCR backend to another engine?
Yes, replace the OCR call in the backend module while preserving the input/output contracts.
Is this production-ready?
The template provides production-oriented rules and structure. Validate, test, and adapt to your infrastructure.