Angular Material + FastAPI MongoDB CLAUDE.md Template

Overview


Direct answer: This CLAUDE.md Template provides a copyable Claude Code instruction block tailored for a stack combining Angular Material frontend, FastAPI backend, and MongoDB database. It yields a complete starter with project roles, rules, and file structure to accelerate scaffolding.


The template guides Claude Code to generate a cohesive, production-ready starter with frontend components, API endpoints, data models, and security considerations aligned to this stack.



When to Use This CLAUDE.md Template



  - Start a new Angular Material + FastAPI + MongoDB project with a repeatable blueprint.

  - Ensure consistent architecture, file layout, and security guidelines across teams.

  - Generate a Claude Code block that yields a first-pass, runnable scaffold with tests.

  - Document stack-specific constraints and best practices in a reusable template.



Copyable CLAUDE.md Template


Copyable CLAUDE.md template for the stack. Paste into CLAUDE.md to generate starter code.


# CLAUDE.md
Project role: You are Claude Code, a code-generation assistant that produces a clean, opinionated starter for an Angular Material + FastAPI + MongoDB project. The output should be a complete, ready-to-run scaffold that a developer can paste into a repository and start from.
Architecture rules:
- Frontend: Angular 15+ with Angular Material components, routing, and a minimal linear workflow.
- Backend: FastAPI with Pydantic models, dependency injection, async endpoints, and JWT-based authentication.
- Database: MongoDB (MongoDB Atlas or locally) accessed via Motor (async driver).
- API surface: RESTful endpoints with clear, versioned paths under /api/v1.
- Data contracts: Use Pydantic models for request/response validation; use MongoDB models with proper indexes.
- Authorization: JWTs via OAuth2PasswordBearer; tokens issued by /api/v1/auth/login; include refresh strategy with httpOnly cookies if possible.
- Error handling: Centralized exception handlers with consistent HTTP status codes.
File structure rules:
- Do not put frontend and backend in the same project root unless you intend a monorepo; prefer clear folders: frontend/, backend/.
- frontend/ should contain angular.json, package.json, tsconfig.*, and src/ with app/, assets/, environments/.
- backend/ should contain main.py, app/, models/, api/, services/, core/, tests/.
- db/ folder contains seed scripts and MongoDB initialization if needed.
- Do not create random additional folders not needed for the stack.
Authentication rules:
- Use JWTs for API authentication; store access token in Authorization header; prefer httpOnly refresh cookies if a SPA supports it.
- Password hashing with bcrypt; store user data securely; never store plain-text passwords.
- Validate all inputs on both client and server; reject invalid tokens.
Database rules:
- Use MongoDB with Motor; keep connections async; set a reasonable connection pool.
- Use environment variables for connection strings: MONGO_URI, JWT_SECRET, JWT_ALGORITHM, JWT_EXPIRE_MINUTES.
- Ensure indexes on users.email (unique) and any frequently queried fields, like posts.slug.
Validation rules:
- Pydantic models for requests and responses; use discriminated unions if needed for polymorphic payloads.
- Validate all inputs on the API boundary; return 400 for invalid input.
Security rules:
- Do not commit secrets to VCS; use environment variables; enable HTTPS in production; configure CORS carefully; implement CSRF protections where applicable for SPA.
- Do not bypass authentication for read endpoints unless intended; avoid exposing internal server details in errors.
Testing rules:
- Backend: pytest with httpx for API tests; test auth flows, CRUD operations, error paths.
- Frontend: lightweight unit tests with Jest and integration tests with Playwright or Cypress; mock server endpoints.
- Run tests as part of CI; ensure all tests pass locally.
Deployment rules:
- Dockerfile for frontend and backend; docker-compose.yml for local development; Kubernetes manifests for deployment in prod if applicable.
- Use multi-stage builds; minimize image size; pin exact versions.
- Environment variables per service; provide defaults for local dev.
- Perform migrations as needed; seed data for local dev.
Things Claude must not do:
- Do not assume Prisma, Mongoose, Drizzle, or ORMs not part of the stack.
- Do not generate code that relies on serverless-only features; avoid vendor-lock-in.
- Do not generate hardcoded secrets; do not output API keys or credentials.
- Do not propose insecure patterns (e.g., storing JWTs in localStorage without protection).
- Do not perform client-side file system writes outside allowed browser APIs.
- Do not suggest non-production patterns (e.g., global state anti-patterns in Angular).
- Do not propose deprecated Angular features; avoid outdated APIs.
- Do not auto-create database schemas outside migrations (no implicit migrations in this template).
- Do not use unsupported libraries for this stack.

Recommended Project Structure


frontend/
  angular.json
  package.json
  tsconfig.json
  src/
    app/
      components/
        material/
      pages/
      environments/
      styles.css
backend/
  main.py
  requirements.txt
  src/
    main/
      api/
      models/
      services/
      core/
docker-compose.yml
 
Core Engineering Principles



  - Clear separation of concerns between frontend, backend, and data layer.

  - Strong typing across TypeScript and Python boundaries with Pydantic and TypeScript interfaces.

  - Async I/O everywhere for I/O-bound operations.

  - Defensive programming with input validation and explicit error handling.

  - Idempotent API design with meaningful status codes and retries.

  - Observability: structured logging, metrics, and tracing ready for production.

  - Maintainable code with clean architecture and proper documentation.


Code Construction Rules



  - Frontend must use Angular Material components with responsive layouts.

  - Backend API must expose versioned endpoints under /api/v1.

  - MongoDB collections must have appropriate indexes; enforce unique constraints where requested.

  - DTOs for API requests and responses must be explicit and validated.

  - Use dependency injection and Pydantic/BaseModel in FastAPI; ensure async endpoints.

  - Do not use global mutable state; avoid side effects in tests.


Security and Production Rules



  - Use JWT-based auth with secure cookie handling where supported; prefer httpOnly cookies for refresh tokens.

  - Enforce CORS and HTTPS in production; validate TLS termination externally.

  - Do not log sensitive information; mask or omit secrets.

  - Ensure secrets are stored in environment variables, not in code.


Testing Checklist



  - Backend: pytest; tests for auth, endpoints, error handling.

  - Frontend: unit tests and integration tests; mock API calls.

  - CI should run linting and tests on PRs.


Common Mistakes to Avoid



  - Hardcoding configuration or secrets; forgetting to seed DB for local dev.

  - Mixing frontend and backend stacks in a single project root without clear boundaries.

  - Missing input validation and weak error handling.


FAQ



  - 
    Q: How to begin integrating CLAUDE.md Template?
    
A: Follow the steps in this CLAUDE.md template to scaffold frontend, backend, and DB with best practices.
  

  - 
    Q: Can I customize the stack?
    
A: Yes, adjust the instruction blocks to match your stack while keeping Claude rules consistent.
  

  - 
    Q: How do I test the authentication flow?
    
A: Use the provided backend tests for login/endpoints and frontend tests to exercise protected routes.
  

  - 
    Q: Where should I store secrets for local development?
    
A: Use environment variables and a local .env file ignored by VCS; do not commit secrets.
  

  - 
    Q: Is Docker required for this starter?
    
A: Docker is recommended for consistency, but you can run frontend and backend natively as described in the deployment rules.