CLAUDE.md Template for Angular Material + FastAPI Inventory Management

Overview

The CLAUDE.md template is a copyable Claude Code blueprint tailored for an Angular Material + FastAPI inventory management stack. It defines a clear project role, architecture rules, file structure, authentication, data validation, security, testing, and deployment guidance. This page is a single, paste-ready CLAUDE.md template you can drop into a Claude Code project to generate consistent, production-ready guidance for this stack.

Direct answer: Use this CLAUDE.md template to produce a complete developer-facing blueprint for an Angular Material frontend with a FastAPI backend and PostgreSQL database, including rules, structure, and deployment steps.

When to Use This CLAUDE.md Template

• Starting a new inventory management project with Angular Material and FastAPI.
• Standardizing Claude Code outputs across frontend-backend collaboration.
• Defining consistent security, validation, and deployment rules for the stack.
• Onboarding new team members with a runnable blueprint for architecture and file structure.

Copyable CLAUDE.md Template

# CLAUDE.md

# CLAUDE.md Template for Angular Material + FastAPI Inventory Management

Project role:
- You are Claude Code for building a production-ready inventory app with an Angular Material frontend and a FastAPI backend. Your outputs must guide both UI and API design, data models, and deployment.

Architecture rules:
- Frontend: Angular Material SPA consuming REST endpoints at /api/* served from a static build.
- Backend: FastAPI REST API powered by PostgreSQL. Use async endpoints where appropriate and Pydantic models for validation.
- DB: PostgreSQL with schemas: users, items, inventory_movements. Use foreign keys and proper indexing on inventory_id and item_id.
- Communication: JSON over HTTPS with JWT-based auth in Authorization headers. Backend validates tokens for protected routes.

File structure rules:
- Frontend: angular-app/
  - src/app/components/
  - src/app/pages/
  - src/app/services/
  - angular.json, package.json
- Backend: backend-app/
  - app/main.py
  - app/api/
  - app/models/
  - app/schemas/
  - requirements.txt
- Infra: docker-compose.yml, .env.example, README.md

Authentication rules:
- Use JWTs with access and refresh tokens; store refresh tokens securely server-side or in a short-lived cookie when used with SPA.
- Passwords stored with bcrypt; never plaintext.
- Admin vs user scopes must be clearly enforced at endpoint level.

Database rules:
- PostgreSQL database with schemas: users(id, email, hashed_password, role), items(id, name, sku, quantity, location), inventory_movements(id, item_id, change, timestamp, user_id).
- Enforce foreign keys and constraints; index on item_id and timestamp for queries.

Validation rules:
- FastAPI: Pydantic models for request/response validation; strict typing for payloads.
- Frontend: TypeScript interfaces for API payloads; runtime checks where necessary.

Security rules:
- Use HTTPS in production; enable CORS with specific origins for SPA only.
- Do not log sensitive data; mask identifiers when displaying in UI.
- Session handling must avoid CSRF vulnerabilities; use Authorization header tokens for API calls.

Testing rules:
- Backend: unit tests for models and endpoints; integration tests for inventory flow (add item, adjust quantity, audit movements).
- Frontend: unit tests for components/services; end-to-end smoke tests for common user flows.

Deployment rules:
- Build frontend and serve static assets; run backend with Uvicorn in production. Use docker-compose for dev/staging with a Postgres service.
- Secrets and env vars must be provided at runtime, not hard-coded.

Things Claude must not do:
- Do not propose insecure auth schemes or plaintext credentials.
- Do not assume a different stack without explicit instruction.
- Do not bypass validation or skip unit/integration tests.

Recommended Project Structure

frontend-angular/
  angular.json
  package.json
  src/
    app/
      components/
      services/
      pages/
      app.module.ts
backend-fastapi/
  app/
    __init__.py
    main.py
    api/
      items.py
      auth.py
    models/
      item.py
      user.py
    schemas/
      item_schema.py
      user_schema.py
  requirements.txt
  database/
    migrations/
docker-compose.yml
.env

Core Engineering Principles

• Strong API/API-contract discipline between Angular Material frontend and FastAPI backend.
• Type-safe development with Pydantic on the backend and TypeScript interfaces on the frontend.
• Clear separation of concerns: UI concerns in frontend, data access in backend.
• Idempotent and observable backend endpoints with proper error handling.
• Secure by default: authenticated endpoints, encrypted secrets, and minimal privileges.

Code Construction Rules

• Frontend components must use Angular Material table with sorting, pagination, and filtering for inventory items.
• Backend endpoints should expose CRUD operations for items and a simple audit trail for movements.
• Models must be explicit: CreateItem, UpdateItem, ItemResponse, UserResponse, MovementRecord.
• Authentication: JWT with short-lived access token; refresh flow if applicable.
• Validation: Always validate request bodies against Pydantic models on API; reject invalid data early.
• Security: Do not expose internal IDs in API responses unless required; use opaque identifiers if possible.
• Testing: No test should rely on non-deterministic data; seed tests deterministically.
• Deployment: Provide a docker-compose.yml for development with separate services for frontend, backend, and postgres.
• Do not: hard-code credentials; bypass CORS; skip tests; bypass validation.

Security and Production Rules

• Enable HTTPS in all environments; redirect HTTP to HTTPS in prod.
• Use HTTP-only, Secure cookies if token storage is cookie-based; otherwise use Authorization header with Bearer tokens.
• Hash and salt all passwords with bcrypt; never store plain passwords.
• Limit API rate per user; enable basic WAF rules on edge if possible.
• Environment-based configuration: no secrets in code; use secret management and env vars.

Testing Checklist

• Unit tests for item and user models in backend.
• Endpoint tests for create/read/update/delete items and movement logs.
• Authentication tests for login, token refresh, and protected routes.
• Frontend tests for inventory listing, search, and item detail views.
• CI/CD: run unit tests on push; run full test suite on PRs; ensure linting passes.

Common Mistakes to Avoid

• Assuming frontend and backend can share runtime types without a contract; keep schemas in sync.
• Skipping input validation or relying on client-side validation only.
• Hard-coding secrets or using insecure token storage approaches.
• Ignoring proper database indexing leading to slow queries on inventory history.

FAQ

What is this CLAUDE.md Template for?

It provides a ready-to-paste CLAUDE.md block for an Angular Material + FastAPI inventory app with rules, structure, and deployment guidance.

What stack does it target?

Angular Material frontend and FastAPI backend with PostgreSQL, using JWT-based authentication and REST endpoints.

What should I paste into CLAUDE.md?

The code block starting with # CLAUDE.md; contains Claude Code instructions as per the template.

What are deployment considerations?

Provide docker-compose for frontend/backend, environment variables, secret management, and HTTPS in production.

What are common mistakes to avoid?

Hard-coding secrets, skipping validation, ignoring CORS, and using permissive auth.