Angular Material + FastAPI Secure File Sharing — CLAUDE.md Template

Overview

This CLAUDE.md template documents a starter stack for secure file sharing using Angular Material on the frontend and FastAPI on the backend. It demonstrates a reproducible CLAUDE.md workflow for a modern, secure web app with a focus on type safety, authentication, and secure storage integration.

When to Use This CLAUDE.md Template

• You are building a secure file sharing app with a rich UI built on Angular Material.
• You need a clear, copyable CLAUDE.md starter to define architecture, tests, and deployment for both frontend and backend.
• You want a repeatable contract for Claude Code to scaffold code, tests, and security checks.
• You require strict authentication, input validation, and secure storage for files and metadata.

Copyable CLAUDE.md Template

# CLAUDE.md

Project role: Full-stack Developer (Angular Material frontend + FastAPI backend) building secure file sharing.

Architecture rules:
- Frontend talks to backend via REST APIs; backend exposes protected endpoints with JWT authentication.
- Store file metadata in Postgres; store actual files in S3-compatible object storage with server-side encryption.
- All endpoints use TLS; tokens are transmitted in HttpOnly cookies or via secure headers.
- Do not bypass authentication or authorization checks.

File Structure Rules:
- Root
  - frontend
  - backend
  - infra
  - docs
- Frontend contains an Angular project with Material UI and feature modules for auth and file sharing.
- Backend contains a FastAPI app with routers for auth, users, and files, plus models and services.
- Tests live under tests in both frontend and backend folders.

Authentication rules:
- Use OAuth2 / JWT with short-lived access tokens and refresh tokens.
- Store tokens in HttpOnly, Secure cookies; enforce same-site policy.
- Endpoints require a valid access token; refresh when expired via a dedicated endpoint.

Database rules:
- Postgres for metadata and user accounts.
- No file content storage in the database; use object storage with signed URLs for access.
- Enforce unique constraints on file IDs and user roles.

Validation rules:
- Backend: Pydantic models with strict type validation; explicit field requirements.
- Frontend: Angular forms with synchronous and async validators; guard against invalid uploads.

Security rules:
- Validate file types and sizes; reject executable files and overly large uploads.
- Enable CORS only for known origins; enforce CSRF protections for mutating requests via cookies.
- Implement rate limiting and audit logging for sensitive endpoints.

Testing rules:
- Backend: pytest with test clients; unit tests for models and routers; integration tests for auth and file endpoints.
- Frontend: Jest + Angular testing; component and service tests; UI accessibility tests.
- CI should run unit and integration tests on every PR; deploy previews on merge.

Deployment rules:
- Local: docker-compose up to run frontend and backend with a local postgres and minio/s3 mock.
- Production: containerized services; Kubernetes with manifest-driven deployments; secrets via Kubernetes Secrets; TLS via certificate manager.

Things Claude must not do:
- Do not bypass auth or authorization checks.
- Do not read or commit real secret keys in code or configs.
- Do not expose private data or internal endpoints publicly.

Recommended Project Structure

project-root/
├── frontend/
│   ├── src/
│   │   ├── app/
│   │   │   ├── components/
│   │   │   ├── services/
│   │   │   └── pages/
│   │   ├── index.html
│   │   └── main.ts
│   ├── angular.json
│   ├── package.json
│   └── tsconfig.json
├── backend/
│   ├── app/
│   │   ├── api/
│   │   │   ├── auth.py
│   │   │   ├── files.py
│   │   │   └── users.py
│   │   ├── models/
│   │   ├── routers/
│   │   └── services/
│   ├── main.py
│   ├── requirements.txt
│   └── Dockerfile
├── infra/
│   ├── docker-compose.yml
│   └── k8s/
└── docs/
    └── claude-md-templates/

Core Engineering Principles

• Security-first design with explicit data flow and least privilege access
• Explicit contracts between frontend and backend via well-defined APIs
• Type safety and validation at every boundary (Pydantic, Angular forms)
• Observability through structured logging and metrics
• Reproducible builds and deterministic deployments

Code Construction Rules

• Frontend uses Angular with Material components and well-scoped feature modules
• Backend uses FastAPI with Pydantic models for request/response validation
• JWT tokens with short lifetimes; refresh tokens on secure cookies
• File storage on object storage, not database; signed URLs for access
• Environment variables for secrets; no hardcoded keys
• Consistent naming, formatting, and linting across both stacks
• Do not rely on client-side validation alone for security

Security and Production Rules

• TLS everywhere; enforce HTTPS in all environments
• CORS restricted to known origins; anti-CSRF protections for state-changing requests
• Audit logs for authentication, file access, and admin actions
• Input validation and content filtering to prevent injections
• Regular dependency scanning and image provenance controls

Testing Checklist

• Backend: unit tests for models, validators, and routers; integration tests for auth and file APIs
• Frontend: unit tests for components and services; e2e tests for file upload/download flows
• CI: run tests on pull requests; build and publish container images with versioned tags
• Deployment: smoke tests after deployment; verify TLS and token issuance

Common Mistakes to Avoid

• Assuming frontend validation is enough for security
• Storing large files in the database or without encryption
• Improperly scoped CORS or overly permissive access controls
• Hardcoding secrets or credentials in code or configs

FAQ

What is this CLAUDE.md Template for?

A copyable CLAUDE.md starter for building a secure Angular Material frontend with a FastAPI backend for file sharing.

Which stack does it cover?

Angular Material frontend and FastAPI backend with Postgres metadata and S3-like object storage for files.

How do I run this template locally?

Clone the project, run docker-compose up to start frontend and backend services with local dependencies, then access the app locally.

How is authentication handled?

JWT access tokens stored in HttpOnly cookies with refresh tokens; protected endpoints require a valid token.

What should I not do?

Do not bypass authentication, expose keys, or store file contents in the DB. Do not deploy with permissive CORS.