CLAUDE.md Template: Angular Material + FastAPI Marketplace App

Overview

CLAUDE.md Template for Angular Material + FastAPI Marketplace App provides a concrete, copyable Claude Code block to scaffold a full-stack marketplace. It targets a frontend built with Angular Material and a backend powered by FastAPI, connected to PostgreSQL. It includes role definitions, architecture rules, file structure, and deployment guidance tailored for this stack. Direct answer: you can paste the Claude Code block into CLAUDE.md to generate a complete, end-to-end starter for an Angular Material + FastAPI marketplace.

When to Use This CLAUDE.md Template

• When you need a ready-to-paste CLAUDE Code template for a full-stack marketplace using Angular Material and FastAPI.
• When your team wants explicit project roles, architecture constraints, and deployment guidance to minimize drift.
• When you want a consistent, maintainable file structure with clear authentication, validation, and security rules.

Copyable CLAUDE.md Template

# CLAUDE.md

Project Role: Senior full-stack engineer for an Angular Material frontend + FastAPI backend marketplace.

Architecture Rules:
- Separate frontend and backend services; REST API design with versioning; public endpoints protected by JWT-based auth.
- Frontend uses Angular Material components; backend uses FastAPI with PostgreSQL; database access via SQLModel/SQLAlchemy models.
- Data flow: frontend calls backend REST endpoints, backend validates and stores data in PostgreSQL; monitoring via logs and metrics.

File Structure Rules:
- frontend/: Angular project (src/app, assets, environments, angular.json, package.json).
- backend/: FastAPI project (app/, models/, api/, core/, main.py, requirements.txt).
- tests/: unit and integration tests for backend and frontend.

Authentication Rules:
- Use OAuth2 Password Flow with JWT access tokens and refresh tokens.
- Access tokens short-lived; refresh tokens rotated securely.
- Store tokens securely on client (HttpOnly cookies for refresh tokens if possible).

Database Rules:
- PostgreSQL with strict schemas; migrations via Alembic or equivalent.
- Use SQLModel/SQLAlchemy models for type-safe queries; enforce constraints at DB level.

Validation Rules:
- Pydantic models for request/response validation on FastAPI endpoints.
- Validate input lengths, formats, and required fields server-side; frontend should mirror schemas.

Security Rules:
- HTTPS enforced in prod; CORS restricted to frontend domain; no sensitive data in frontend storage.
- Input sanitization and output escaping to protect against XSS/SQL injection.

Testing Rules:
- Backend: PyTest with fixtures for DB setup; test authentication, CRUD endpoints, and validation.
- Frontend: Angular testing with Jest/Karma and end-to-end tests if possible; mock API calls.

Deployment Rules:
- Local: Docker Compose with frontend and backend services.
- Production: Kubernetes manifests or cloud-run deployment; separate secrets management.

Things Claude Must Not Do:
- Do not generate code with hard-coded secrets or insecure credentials.
- Do not bypass authentication checks or authorization rules.
- Do not create endpoints that expose admin-only data publicly.
- Do not rely on deprecated libraries or non-existent APIs.

Recommended Project Structure

frontend/
  angular.json
  package.json
  tsconfig.json
  src/
    app/
      components/
      pages/
      app.module.ts
      app-routing.module.ts
    assets/
    environments/
backend/
  app/
    api/
      endpoints/
    models/
    core/
    main.py
  tests/
  Dockerfile
  docker-compose.yml
  requirements.txt
  alembic/

Core Engineering Principles

• Explicit contracts: enforce clear input/output schemas between frontend and backend.
• Type safety: use TypeScript on the frontend and Pydantic/SQLModel on the backend.
• Security by default: authentication, validation, and least privilege access from day one.
• Separation of concerns: strict boundaries between UI, API, and data layers.
• Testability: structure code to enable unit, integration, and end-to-end tests.

Code Construction Rules

• Frontend must rely on Angular Material components and responsive design patterns.
• Backend endpoints must be documented, versioned, and validated with Pydantic models.
• Use PostgreSQL with migrations; avoid embedding raw SQL in business logic.
• Models and schemas should be interoperable between frontend and backend via shared contracts where feasible.
• Do not bypass validation or security checks in the code path.

Security and Production Rules

• Enable HTTPS in all production environments; enforce secure cookies and token storage practices.
• Restrict CORS to the frontend domain; implement proper origin checks.
• Protect endpoints with role-based access control where applicable.
• Use environment-specific configurations; avoid leaking secrets in code or images.

Testing Checklist

• Backend: test authentication flow, CRUD endpoints, validation errors, and error handling.
• Frontend: test component rendering with mock data, API integration, and responsive layouts.
• Deployment: smoke tests in staging; verify containerization and orchestration scripts.

Common Mistakes to Avoid

• Weak or no input validation leading to security holes.
• Overlapping responsibilities between frontend and backend that cause drift.
• Hard-coded secrets or credentials in code or configuration.
• Skipping migrations or relying on in-memory databases in production.

FAQ