Angular Material + FastAPI Image Upload App CLAUDE.md Template

Overview

A CLAUDE.md template designed for a stack consisting of Angular Material on the frontend and FastAPI on the backend to handle image uploads. This page provides a copyable CLAUDE.md block and stack-specific guidelines so developers can paste directly into CLAUDE.md to scaffold the project.

Direct answer: This CLAUDE.md Template delivers a complete blueprint for a full-stack image upload app using Angular Material and FastAPI, including authentication, storage, validation, and deployment rules.

When to Use This CLAUDE.md Template

• Starting a new Angular Material + FastAPI image upload project with a reproducible Claude Code blueprint.
• Requiring stack-specific rules for architecture, file structure, validation, and security.
• Seeking a copyable CLAUDE.md Template that guides both frontend and backend development.

Copyable CLAUDE.md Template

# CLAUDE.md
Project role
- You are a full-stack engineer responsible for implementing an Angular Material frontend and a FastAPI backend to support image uploads.

Architecture rules
- Frontend: Angular Material UI consuming a REST API from FastAPI
- Backend: FastAPI app with UploadFile handling, Pydantic models, JWT-based auth, and a simple SQLite/PostgreSQL setup
- Use a single uploads/ directory for storage in development; abstract storage to allow swap to S3 or similar in prod
- Deploy with Docker Compose for local development

File structure rules
- Frontend: angular-app/src/app/
- Backend: backend/app/
- Shared code in backend/app/models and frontend/src/app/models where applicable
- Do not mix server and client code in the same directory
- Use environment-driven configuration

Authentication rules
- Use JWT tokens issued by an auth endpoint; require Authorization header with Bearer token
- Do not hard-code secrets in the repo
- Validate token at backend endpoints that modify data

Database rules
- Use SQLite for local development; switch to PostgreSQL in production
- Store image metadata in a DB table with fields id, filename, size, mime_type, uploaded_at

Validation rules
- Validate image mime types to be image/jpeg or image/png
- Enforce max file size of 5 MB per upload
- Validate that uploaded file names are sanitized

Security rules
- Enable CORS for the frontend domain only
- Serve uploaded files securely; avoid exposing arbitrary filesystem paths
- Do not expose internal stack traces in API responses
- Use TLS in production

Testing rules
- Unit tests for backend endpoints using pytest
- Integration tests for upload flow
- Frontend tests should cover file input and API integration
- End-to-end tests for the upload flow (optional)

Deployment rules
- Use Docker Compose for local development: frontend served by a static server, backend by uvicorn
- Production deployment uses a reverse proxy (e.g., Nginx) and a running API service
- Secrets must be provided via environment variables

Things Claude must not do
- Do not bypass authentication or store tokens insecurely
- Do not upload to local disk in production without a secure path
- Do not implement image processing steps without explicit requirement

Recommended Project Structure

frontend/
  angular-app/
    src/
      app/
        components/
        services/
        models/
      assets/
      environments/
    angular.json
    package.json
backend/
  app/
    main.py
    api/
      endpoints/
      routers/
    models/
    schemas/
  uploads/
  requirements.txt

Core Engineering Principles

• Separation of concerns between frontend and backend
• Strong typing with TypeScript and Pydantic for data shapes
• API-first design with clear contracts
• Secure defaults and least privilege philosophies
• Observability through structured logging and error handling
• Idempotent, retry-friendly operations for uploads

Code Construction Rules

• Frontend uses Angular Material components for file input and previews
• Backend uses FastAPI UploadFile with dependency injection for auth
• Files are validated, sanitized, and stored with sanitized filenames
• Backend returns a metadata response with file URL and mime type
• Environment variables drive configuration; no hard-coded secrets
• Use Pydantic models for request/response schemas
• Do not rely on non-listed libraries or shortcuts outside this template

Security and Production Rules

• Configure CORS to allow only the Angular frontend origin
• Validate and sanitize all inputs; never trust client-provided metadata
• Store uploaded files outside the repository; use a dedicated uploads directory
• Produce concise error messages without leaking internal details
• Enable TLS in production and rotate credentials securely

Testing Checklist

• Backend unit tests for upload endpoint with valid and invalid inputs
• Integration tests covering authentication and file saving
• Frontend tests for file input and API interaction
• End-to-end tests for the upload flow (optional)

Common Mistakes to Avoid

• Assuming client-side validation is sufficient
• Storing secrets in code or in public repos
• Skipping validation for file types and sizes
• Overlooking security headers and CORS configurations

FAQ