Angular Material + FastAPI Document Intelligence App CLAUDE.md Template

Overview

CLAUDE.md template for building an Angular Material + FastAPI Document Intelligence app. This page is a copyable CLAUDE.md template page designed for Claude Code, tailored to a stack that combines a polished Angular Material frontend with a FastAPI backend for document processing, OCR, and content extraction. Direct answer: use this template to scaffold a reproducible full-stack starter with clear architecture, file structure, and Claude Code instructions.

When to Use This CLAUDE.md Template

• When you need a reproducible starter for a document intelligence app with Angular Material UI and a FastAPI API.
• When your project requires document ingestion (PDF/DOCX), OCR, and text extraction workflows.
• When frontend/backend separation and a clean monorepo organization is desired.
• When you want Claude Code to generate scaffolded code, tests, and deployment scripts for this stack.
• When JWT-based authentication and PostgreSQL data storage are part of the plan.

Copyable CLAUDE.md Template

# CLAUDE.md

Project role
- You are Claude Code. Your job is to generate a production-ready starter for an Angular Material + FastAPI Document Intelligence app. Provide precise, stack-specific guidance and concrete file-level instructions that can be pasted into CLAUDE.md.

Architecture rules
- Maintain clear frontend/backend separation.
- Use an Angular 16+ frontend with Angular Material and a FastAPI backend.
- Place frontend under client/ and backend under server/ in a monorepo.
- Expose a REST API under /api on FastAPI; document logical endpoints with OpenAPI schemas.
- Use a Postgres database via SQLModel/SQLAlchemy with Alembic migrations.
- Data sent to Claude Code should be validated via Pydantic/Type hints and not rely on client trust.

File structure rules
- client/ for Angular app; server/ for FastAPI.
- client/src/app/ contains components, services, and modules; server/app/ contains api, core, models, schemas, and routers.
- Include a README with setup steps and environment variable references.

Authentication rules
- Use OAuth2 Password flow with JWT access/refresh tokens.
- Store refresh tokens securely; use HTTP-only cookies or Authorization header as appropriate.
- Passwords must be hashed with a strong algorithm (e.g., bcrypt) and never stored in plaintext.

Database rules
- Use PostgreSQL with SQLModel/SQLAlchemy.
- Use Alembic for migrations; initialize a migrations folder and provide a baseline migration.
- Validate all inputs; enforce unique constraints where required (e.g., users by email).

Validation rules
- Use Pydantic models for request/response validation on the FastAPI side.
- Validate file uploads: only allow PDFs and common document formats; limit file size.
- Normalize and sanitize inputs; return structured error messages.

Security rules
- Enforce HTTPS in production and avoid mixed content.
- Validate JWT and scopes on each protected endpoint.
- Do not include secrets in code; load from environment variables.
- Disable debug endpoints in production.

Testing rules
- Backend: pytest with httpx for API tests; coverage checks.
- Frontend: unit tests with Angular testing utilities; end-to-end tests with Cypress.
- Include a small set of integration tests around file upload and OCR flow.

Deployment rules
- Provide Dockerfiles for client and server and a docker-compose.yml to run both together.
- Use Gunicorn/Uvicorn in production; reverse proxy with Nginx in a separate container if applicable.
- Secrets should be supplied via environment variables; use a .env.example in repo.

Things Claude must not do
- Do not hardcode secrets or API keys.
- Do not bypass authentication or validation checks.
- Do not generate insecure CORS configurations for production.
- Do not reference or require non-existent services without clear setup steps.

Recommended Project Structure

root/
├── client/
│   ├── angular.json
│   ├── package.json
│   └── src/
│       └── app/
│           ├── core/
│           ├── models/
│           ├── services/
│           └── components/
├── server/
│   ├── main.py
│   └── app/
│       ├── api/
│       ├── core/
│       ├── models/
│       ├── schemas/
│       └── routers/
├── migrations/  (Alembic)
├── docker-compose.yml
└── README.md

Core Engineering Principles

• Clarity and simplicity: easy to read and modify.
• Type safety and explicit contracts: use Pydantic/Type hints everywhere.
• Security by default: proper authentication, input validation, and least privilege DB access.
• Automation: tests, linting, and CI/CD as part of the template.
• Maintainability: clean module boundaries and documentation in code comments.
• DX focus: consistent naming, meaningful error messages, and developer-friendly scaffolding.

Code Construction Rules

• Frontend: Angular Material components for UI; feature modules with lazy loading.
• Backend: FastAPI with Pydantic models; use SQLModel/SQLAlchemy for DB access; create CRUD routers.
• API design: RESTful endpoints; versioned if needed; explicit response models.
• Validation: strict Pydantic models and input validation; reject invalid file types/limits.
• Authentication: JWT tokens; secure handling of access/refresh tokens.
• Error handling: consistent error responses with codes and messages.
• Testing: unit tests for utilities, integration tests for endpoints, and end-to-end tests for flows.
• Deployment: Docker-based; separate images for client and server; environment-specific config.
• Do not
• Do not bypass validation or authentication; do not embed secrets in code.

Security and Production Rules

• Use HTTPS in all environments; enforce secure cookies if used.
• Validate JWT on all protected endpoints; implement scopes/permissions.
• Limit file upload sizes and types; sanitize file contents before processing.
• Audit logging for critical actions; avoid logging sensitive data.
• Regularly rotate secrets and use environment variables for config.
• Container best practices: non-root containers, minimal base images, and image scanning.

Testing Checklist

• Backend: unit tests for models, endpoints, and business logic; integration tests for DB access.
• Frontend: unit tests for components/services; integration tests for UI flows; E2E tests for OCR/upload workflow.
• Performance: basic load test plan and caching considerations.
• Security: basic vulnerability checks for dependencies and input validation coverage.
• CI/CD: run tests on PRs, linting, type checks, and build verification.

Common Mistakes to Avoid

• Overloading the frontend with backend logic; keep concerns separated.
• Skipping input validation or trusting client-side validation only.
• Relying on insecure storage of secrets or unverified dependencies.
• Not sealing endpoints with proper authentication checks.
• Failing to update migrations when models change.

FAQ

Q: What is CLAUDE.md Template?

A: A copyable CLAUDE.md template page designed for a specific stack to guide Claude Code.

Q: Which stack does this template cover?

A: Angular Material frontend with a FastAPI backend for a Document Intelligence app.

Q: What should I paste into CLAUDE.md?

A: The code block starting with # CLAUDE.md contains practical instructions that you can paste into a CLAUDE.md file.

Q: Can this template be used for other stacks?

A: Yes, but this page is tailored for an Angular Material + FastAPI Document Intelligence stack.

Q: Does Claude Code generate tests?

A: The template includes testing guidelines using pytest for backend and Angular tests for frontend.