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

Related implementation resources: AI Use Case for Demolition Contractors Using Sensor Logs To Optimize Explosive Placement for Safe Building Implosions and Skill files for secure file upload implementations in production AI systems.

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.