Angular Material + FastAPI Audit Trail App CLAUDE.md Template - CLAUDE.md template

Overview

CLAUDE.md template for an audit trail app built with Angular Material on the frontend and FastAPI on the backend. It includes a copyable Claude Code block and stack-specific guidance to scaffold a production-ready solution.

Direct answer: Paste the CLAUDE.md template block below into CLAUDE.md to bootstrap the project structure and coding conventions for this stack.

When to Use This CLAUDE.md Template

• Starting a new audit trail UI backed by a FastAPI service
• Enforcing a consistent CLAUDE Code workflow for frontend and backend across teams
• Seeking a ready-to-paste code block with project role, rules, and deployment steps

Copyable CLAUDE.md Template

# CLAUDE.md

Below is a complete Claude Code starter tailored for Angular Material + FastAPI audit trail apps. Paste into CLAUDE.md and adjust as needed.

Project role:
- You are Claude Code, a deterministic assistant that writes production-grade CLAUDE.md templates for an Angular Material frontend and FastAPI backend audit trail stack.

Architecture rules:
- Maintain a strict frontend (Angular Material) and backend (FastAPI) separation with a clear API contract.
- Use JWT-based authentication and OAuth2 where appropriate; enforce role-based access on endpoints.
- Persist audit events in PostgreSQL via a robust ORM (SQLAlchemy) and store details as JSONB.
- Implement a thin, stateless backend service with a single source of truth for authentication and auditing.

File structure rules:
- Frontend: frontend-angular/src/app/audit-trail/ and related modules
- Backend: backend-fastapi/app/ with api, core, models, and routers
- Shared types: common/ts and common/models in a single location

Authentication rules:
- JWTs issued by FastAPI; access/refresh tokens with appropriate lifetimes
- Protect endpoints with OAuth2PasswordBearer and HTTPBearer where needed
- Do not expose tokens in storage; use HttpOnly cookies or secure storage for clients

Database rules:
- PostgreSQL database; audit_logs table with fields id, user_id, action, resource, timestamp, details
- Use SQLAlchemy ORM; migrations via Alembic; index on timestamp and user_id

Validation rules:
- Pydantic models for requests/responses on backend; strict field validation and type checking
- Frontend forms validated with Angular reactive forms and Material validators

Security rules:
- Input validation and escaping on both frontend and backend
- Parameterized queries; disable dangerous eval or dynamic query construction
- Enforce TLS in production; limit CORS to known origins; enable CSRF protection where applicable

Testing rules:
- Frontend: unit tests for components/services using Jest or Angular testing utilities
- Backend: unit tests with pytest; integration tests with httpx for API endpoints
- Validate audit log accuracy via end-to-end tests where feasible

Deployment rules:
- Docker Compose with frontend and backend services; environment-based config; run database migrations on startup
- Secrets retrieved from a secure vault or environment variables, not hard-coded

Things Claude must not do:
- Do not hard-code credentials or secrets
- Do not skip tests or deploy without validation
- Do not bypass authentication or authorization checks
- Do not generate unsafe or executable code that could introduce security risks

Recommended Project Structure

frontend-angular/
  src/
    app/
      audit-trail/
        components/
        services/
        pages/
  angular.json
  package.json
backend-fastapi/
  app/
    main.py
    api/
    models/
    routers/
    core/
  requirements.txt
  alembic.ini
docker-compose.yml
README.md

Core Engineering Principles

• Explicit typing and contract-driven development
• Clear separation of concerns between frontend and backend
• Idempotent, auditable API endpoints
• Observability through structured logging and metrics
• Security by default and least privilege access
• Accessible, testable UI components
• Documentation and reproducibility

Code Construction Rules

• Frontend uses Angular Material components (MatToolbar, MatTable, MatFormField, MatInput) with strict typing
• Backend uses FastAPI with Pydantic models; async endpoints where appropriate
• PostgreSQL with SQLAlchemy ORM; Alembic migrations; audit_logs table schema as defined in CLAUDE.md block
• Environment-based configuration; secrets managed securely
• API endpoints have explicit response models and error handling
• Do not rely on insecure eval or dynamic code execution

Security and Production Rules

• JWT-based auth with OAuth2 on the backend; token lifetimes tuned for use case
• HTTPS in production; CORS restricted to known origins
• Audit logs stored securely; sensitive fields redacted where possible
• Input validation and parameterized queries to prevent injection risks
• Regular dependency updates and vulnerability scanning

Testing Checklist

• Frontend unit tests for components and services; UI tests for audit trail views
• Backend unit tests for models, services, and endpoints; integration tests for audit endpoints
• End-to-end tests for common audit flows where feasible
• CI pipelines run tests, linting, and build steps

Common Mistakes to Avoid

• Inconsistent API contracts between frontend and backend
• Storing sensitive data in audit payloads without redaction
• Overcomplicating the data model beyond the audit needs
• Neglecting migrations and backward-compatibility in schema changes
• Skipping tests or production-readiness checks

FAQ

What is this CLAUDE.md Template for?

This template provides a ready-to-paste CLAUDE.md block and stack-specific guidelines for an Angular Material frontend with a FastAPI backend audit trail app.

Which stack does this template cover?

Angular Material frontend and FastAPI backend with PostgreSQL for auditing.

How do I use this template?

Copy the CLAUDE.md block into CLAUDE.md in your project and follow the rules and structure described.

Does it include security and testing guidance?

Yes. It covers authentication, validation, and testing for both frontend and backend.

Can I customize the audit fields?

Yes. Adjust the audit events schema and related models while preserving API contracts.