CLAUDE.md template: Angular Material + FastAPI + MinIO Starter — CLAUDE.md Template

Overview

A CLAUDE.md template for a stack that combines Angular Material front-end, FastAPI back-end, and MinIO object storage. This template provides a copyable Claude Code block and a concrete project structure for building a file storage service with a modern UI, fast API endpoints, and scalable storage via MinIO's S3-compatible interface.

Direct answer: This CLAUDE.md template gives you a ready-to-paste Claude Code block that boots a monorepo with frontend, backend, and MinIO storage, along with explicit rules for architecture, security, testing, and deployment.

When to Use This CLAUDE.md Template

• You need a starter that wireframes an Angular Material UI with a FastAPI API layer and MinIO storage.
• You want a copyable CLAUDE.md block to generate a reproducible project structure.
• You require JWT-based authentication and S3-compatible storage access managed via the backend.
• You aim for a monorepo layout with clear separation between frontend, backend, and storage tooling.

Copyable CLAUDE.md Template

# CLAUDE.md

# Project: Angular Material + FastAPI + MinIO File Storage

- Project role: Full-stack engineer to build an Angular Material frontend, a FastAPI backend, and MinIO-based file storage. Connect frontend to backend and handle file uploads/downloads to MinIO via S3-compatible APIs.
- Architecture rules:
  - Monorepo with three modules: frontend, backend, storage.
  - Local dev via Docker Compose; production via Kubernetes manifests optional.
  - Backend uses FastAPI with Pydantic models; MinIO accessed via minio-py client.
  - All storage operations go through a dedicated API layer with proper authentication.
- File structure rules:
  - frontend/angular-material-app/ with src/app, src/assets, and angular.json
  - backend/app/ with main.py, api/, models/, auth/
  - storage/minio/ with config/ and data/
- Authentication rules:
  - JWT-based authentication; /auth/login issues a token; protected endpoints require Authorization: Bearer<token>
  - Tokens have short expiry and are rotatable via refresh endpoint.
- Database rules:
  - Use SQLite for lightweight metadata; allow overriding to Postgres in prod via environment variables.
  - No direct DB writes from the frontend; all writes go through backend APIs.
- Validation rules:
  - Validate file type and size (e.g., max 100 MB for uploads).
  - Normalize and sanitized file names; reject path traversal attempts.
- Security rules:
  - Do not hardcode secrets; use environment variables and secret management.
  - Use TLS in production; restrict CORS to allowed origins.
  - Use MinIO presigned URLs for direct client access when needed.
- Testing rules:
  - Unit tests for backend models and endpoints; integration tests against a local MinIO instance.
  - Frontend tests using Angular testing utilities; optional E2E with Cypress.
- Deployment rules:
  - Provide docker-compose.yml for local development; Kubernetes manifests for prod when applicable.
  - Use multi-stage builds; keep dependencies minimal.
- Things Claude must not do:
  - Do not bypass authentication or leak credentials.
  - Do not modify production secrets; do not generate or embed private keys.
  - Do not assume cloud keys exist; do not hardcode credentials in code or templates.

Recommended Project Structure

angular-material-fastapi-minio-claude-md-template/
├─ frontend/
│  └─ angular-material-app/
│     ├─ src/
│     │  ├─ app/
│     │  │  ├─ components/
│     │  │  └─ app.module.ts
│     │  └─ main.ts
│     ├─ angular.json
│     └─ package.json
├─ backend/
│  ├─ app/
│  │  ├─ main.py
│  │  ├─ api/
│  │  ├─ models/
│  │  └─ auth/
│  ├─ requirements.txt
│  └─ Dockerfile
├─ storage/
│  └─ minio/
│     ├─ data/
│     └─ config/
└─ docker-compose.yml

Core Engineering Principles

• Clear separation of concerns: frontend, backend, and storage tooling are distinct modules.
• Defensive by design: strict input validation, explicit types, and fail-fast error handling.
• Least privilege: backend uses restricted MinIO credentials; UI limited exposure to storage endpoints.
• Reproducible builds: deterministic Docker images and environment configs.
• Observability: structured logging, tracing, and health checks for all services.
• Security-first by default: use TLS, JWT, and signed URLs; avoid secret leakage.

Code Construction Rules

• Frontend: Angular Material components with strict type-safety; use HttpClient with interceptors for auth.
• Backend: FastAPI with Pydantic models for requests and responses; asynchronous endpoints where appropriate.
• MinIO integration: use minio-py client; store only metadata in SQLite and object data in MinIO buckets.
• Endpoints:
  • POST /api/v1/files/upload
  • GET /api/v1/files/{id}
  • POST /auth/login
• Validation: check MIME type, max size, and sanitized file names; enforce allowed extensions.
• Security: store credentials in environment variables; rotate keys; use CORS restrictions; TLS in prod.
• Testing: unit tests for models, integration tests for storage interactions, and UI tests for frontend.
• Deployment: multi-stage Docker builds; docker-compose for local; optional k8s manifests for prod.
• Do not do: hardcode secrets, bypass auth, bypass CORS, or write direct file system paths from the frontend.

Security and Production Rules

• Enable TLS termination in production and enforce HTTPS only.
• Use signed or temporary URLs for direct client access to MinIO when needed.
• JWT tokens with short lifetimes and refresh tokens; validate token scopes for endpoints.
• MinIO credentials scoped to a dedicated bucket and restricted actions.
• Input validation, size limits, and sanitized file names to prevent injection attacks.

Testing Checklist

• Unit tests for backend models and API endpoints (pytest).
• Integration tests for MinIO interactions using a local MinIO container.
• Frontend unit tests for components and services; ensure auth wiring works.
• End-to-end tests for file upload/download flows (optional Cypress).
• Security tests: validate JWT auth, access control, and input validation.
• Deployment checks: Docker Compose runs, environment variable loading, and health checks.

Common Mistakes to Avoid

• Omitting input validation or relying on client-side validation only.
• Hardcoding credentials or keys in the CLAUDE.md template or generated code.
• Skipping proper error handling and not surfacing meaningful errors to clients.
• Neglecting to scope MinIO access keys properly or exposing them to the frontend.
• Ignoring TLS/HTTPS in production and leaving endpoints publicly accessible.

FAQ

What is this CLAUDE.md Template used for?

It provides a copyable CLAUDE.md template for a stack combining Angular Material frontend, FastAPI backend, and MinIO storage.

Which stack is covered?

Angular Material for UI, FastAPI for API, MinIO for object storage.

How do I use this CLAUDE.md template?

Copy the CLAUDE.md block into your Claude Code environment and adapt paths and credentials to your project.

What security rules are included?

JWT auth, TLS, MinIO client with restricted keys, and input validation.

What is the recommended project structure?

A monorepo with frontend, backend, and storage folders as shown in the template.