CLAUDE.md Template: Angular Material + FastAPI Document Upload App

Overview

A CLAUDE.md template for a document upload application built with Angular Material on the frontend and FastAPI on the backend. It guides you through implementing a complete upload workflow, from UI components to API endpoints and storage considerations.

When to Use This CLAUDE.md Template

• You want a copyable CLAUDE.md template that documents an Angular Material + FastAPI document upload stack.
• You need a consistent architecture blueprint for frontend-backend integration, validation, and deployment.
• You require explicit rules for authentication, storage, and security suitable for production-ish demos.

Copyable CLAUDE.md Template

# CLAUDE.md
Project role: You are a CLAUDE.md template designer for an Angular Material + FastAPI document upload app.
Architecture rules:
- Frontend: Angular 16+ with Angular Material; use HttpClient to call backend APIs.
- Backend: FastAPI with endpoints for /upload, /docs, /docs/{id}; data contracts in JSON; file streams for uploads.
- Storage: Local filesystem in development; optional Amazon S3 in production; ensure paths are sanitized.
- Data contracts: Document metadata as JSON; file payload as multipart/form-data.
File structure rules:
- frontend/
- backend/
- shared/
Authentication rules:
- Use JWT Bearer tokens for protected endpoints; include Authorization header: Bearer .
- Public UI pages may use a dummy token for demos only.
Database rules:
- Use SQLite for local development; migrate for production; store Document metadata and file references.
Validation rules:
- Accept only pdf, doc, docx, png, jpg, jpeg up to 25MB; verify mime type on server and check file extension.
Security rules:
- Validate all inputs; escape and sanitize file names; configure CORS to allow only trusted clients; enable CSRF protection for forms where applicable.
Testing rules:
- Backend: unit tests for /upload, /docs, /docs/{id}; integration tests validating file storage and metadata persistence.
- Frontend: tests for file picker, drag-and-drop, and API calls.
Deployment rules:
- Provide a docker-compose setup with frontend and backend services; environment-specific config via .env files.
Things Claude must not do:
- Do not bypass authentication checks.
- Do not write files outside the designated storage directory.
- Do not hard-code secret keys in the CLAUDE.md block.

Recommended Project Structure

frontend/
  src/
    app/
      components/
      services/
      models/
  angular.json
  package.json
backend/
  main.py
  app/
    api/
    models/
    core/
  requirements.txt
  docker-entrypoint.sh
  Dockerfile
  docker-compose.yml

Core Engineering Principles

• Clear separation of concerns: UI vs API vs storage concerns.
• Explicit contracts: stable interfaces and typed data shapes.
• Security by default: token auth, input validation, least privilege.
• Observability: structured logs, error handling, and metrics scaffolding.
• Deterministic builds and deployments: Dockerized, environment-aware configs.

Code Construction Rules

• Frontend uses Angular Material components and follows the project’s style guide.
• Backend endpoints strictly follow defined schemas; avoid endpoint duplication.
• Use environment variables for sensitive data; never hard-code secrets.
• Validate file uploads on both client and server; sanitize filenames.
• Return consistent JSON responses with status and metadata.

Security and Production Rules

• Enable JWT auth for protected endpoints; validate tokens server-side.
• Configure CORS to allow only trusted origins; deny wildcard origins.
• Enforce file type and size validation; store files with sanitized names.
• Use HTTPS in production; disable verbose error messages in production.
• Audit logs and error reporting; monitor for anomalous uploads.

Testing Checklist

• Unit tests for backend models and validators.
• Integration tests for /upload and /docs endpoints with mock storage.
• End-to-end checks for UI file picker, selection, and API communication.
• Deployment smoke test: build images, run containers, verify endpoints.

Common Mistakes to Avoid

• Assuming frontend validation suffices; server-side validation is required.
• Storing files with unsanitized names causing path traversal risks.
• Exposing raw stack traces in responses; use structured error messages.

FAQ

• Q: What is a CLAUDE.md Template for this stack? A: A copyable Claude Code starter that documents an Angular Material frontend + FastAPI backend for document uploads.
• Q: Which files are included in the template? A: The CLAUDE.md block plus guidance on structure, auth, validation, and tests.
• Q: How do I run the example locally? A: Start the FastAPI server and the Angular app; use the docs API to upload files.
• Q: What security considerations are covered? A: JWT auth, input validation, storage access, and secure deployment tips.
• Q: Can Claude modify or extend the template? A: Yes; it’s designed to be extended for additional endpoints and file types.