CLAUDE.md Template for Angular Material + FastAPI Excel Upload Analyzer

Overview

Direct answer: Use this CLAUDE.md template to configure Claude Code for an Angular Material frontend and FastAPI backend Excel upload analyzer. This page is stack-specific and ready to paste as a CLAUDE.md block.

What this template provides: concrete guidance for a full-stack Angular Material + FastAPI project that handles Excel uploads, parses data on the server, and exposes analysis results via REST endpoints.

When to Use This CLAUDE.md Template

• You are building an Angular Material UI with a FastAPI backend for Excel file uploads.
• You need a copyable CLAUDE.md block to drive Claude Code in your repo.
• You want stack-specific architecture rules, file structure, and deployment constraints in one place.
• You require explicit security, testing, and production rules to prevent drift.

Copyable CLAUDE.md Template

# CLAUDE.md

Project role: Full-stack engineer for Angular Material frontend + FastAPI backend Excel upload analysis.

Architecture rules:
- Client: Angular Material app using Angular 16 components (MatTable, MatFormField, MatDialog)
- Server: FastAPI backend with Pydantic models, async endpoints, and OpenAPI docs
- Data: Excel files (.xlsx) uploaded to /api/upload; server parses and returns analysis results
- Communication: REST/JSON; JWT-based authentication for protected endpoints
- Deployment: Separate frontend and backend services behind a reverse proxy; CI/CD pipelines

File structure rules:
- backend/app/main.py
- backend/app/api/
- backend/app/models.py
- backend/app/schemas.py
- backend/app/services.py
- backend/app/core/
- frontend/src/app/
- frontend/src/styles/

Authentication rules:
- Implement OAuth2PasswordBearer or JWT tokens; refresh tokens optional
- Validate tokens on every protected endpoint
- Do not log raw tokens; store tokens in secure httpOnly cookies when possible

Database rules:
- Use SQLite for development; Postgres for production
- Use SQLAlchemy ORM with async support; create migrations via Alembic
- Do not expose connection strings in code; use environment variables

Validation rules:
- Validate uploaded file type and size (xlsx, under 10 MB)
- Validate Excel schema (required sheets/columns) on upload

Security rules:
- Reject suspicious filenames and path traversal attempts
- Validate and sanitize all inputs; enable CSRF protection for browser clients
- Enforce HTTPS in production; set CORS to allowed origins only

Testing rules:
- Unit tests for Excel parsing (backend)
- Integration tests for /api/upload and /api/analyze
- E2E tests for frontend file upload flow (mock backend)

Deployment rules:
- Dockerize frontend and backend; docker-compose for local dev
- Use environment variables for secrets; rotate keys

Things Claude must not do:
- Do not bypass authentication checks
- Do not rely on in-memory databases for production
- Do not accept password data via URL query parameters

Recommended Project Structure

backend/
  app/
    main.py
    api/
      upload.py
      analyze.py
    models.py
    schemas.py
    services.py
    core/
tests/

frontend/
  src/
    app/
      components/
      services/
  angular.json
  package.json

Core Engineering Principles

• Single source of truth for stack rules in CLAUDE.md blocks
• Explicit typing: type hints in Python and TypeScript
• Separation of concerns: clear frontend/backend responsibilities
• Security by default: validate inputs, restrict file types, and enforce auth
• Repeatable, testable CI/CD and documentation via Claude Code

Code Construction Rules

• Frontend: use Angular Material components; implement file picker and progress UI
• Backend: FastAPI routers with async endpoints; Pydantic models for request/response
• Excel handling: use openpyxl to parse and validate required sheets
• Endpoints: /api/upload for file upload; /api/analyze for analytics
• Validation: check file size, extension, and required columns
• Structures: deposit results to JSON, not binaries, for analyses
• Security: require JWT on protected endpoints; avoid leaking tokens
• Testing: unit tests for validators; integration tests for API
• Deployment: Dockerfile for both services; docker-compose for local and prod
• Do not: rely on ad-hoc global state; skip necessary migrations; embed secrets in code

Security and Production Rules

• Always validate inputs; restrict Excel file MIME types
• Use environment-based configuration; do not hard-code secrets
• Enable CSRF protection for browser clients; use secure cookies
• Implement token expiration and rotation
• Audit logs for authentication events; never log full payloads

Testing Checklist

• Unit tests for Excel parsing logic
• Integration tests for /api/upload and /api/analyze
• Frontend UI tests for file upload flow
• End-to-end tests with docker-compose in CI

Common Mistakes to Avoid

• Skipping server-side validation of Excel content
• Allowing unrestricted file uploads or large payloads
• Not sanitizing filenames and inputs
• Under-securing the API without proper authentication

FAQ