Building Inspection Cursor Rules Template for Python FastAPI + PostgreSQL

Overview


  Cursor rules configuration for building inspection report generators on a Python FastAPI + PostgreSQL stack enables a consistent, audit-friendly development approach. This template tailors Cursor AI guidance to the FastAPI routes, SQLAlchemy models, and report-generation workflows used by building inspectors to produce PDF/HTML reports.


  When to Use These Cursor Rules


  
    - When implementing an API that generates standardized building inspection reports from structured input data.

    - When your stack uses Python 3.11+, FastAPI, PostgreSQL, and SQLAlchemy.

    - When you want enforce coding standards, security, and robust testing for report generation endpoints.

  
  Copyable .cursorrules Configuration


  Framework Role & Context
Role: You are Cursor AI assistant for Python FastAPI + PostgreSQL building inspection report generator.
Context: Create deterministic, testable interactions for generating standardized inspection reports from API input.

Code Style and Style Guides
CodeStyle: Black, isort, flake8; Use PEP8; type hints; mypy where applicable.

Architecture & Directory Rules
Directory: src/app with submodules: api/v1/endpoints, models, schemas, core, db; tests under tests.
Endpoints: keep route handlers thin; business logic in services; pydantic models for input/output.

Authentication & Security Rules
Auth: OAuth2 with JWT tokens; Use fastapi.security.OAuth2PasswordBearer; Never log passwords; Key material from environment.

Database and ORM patterns
DB: PostgreSQL; ORM: SQLAlchemy; Use Alembic; Avoid raw SQL in business logic; Use parametrized queries.

Testing & Linting Workflows
Tests: pytest + httpx; Async endpoints tested with AsyncClient; Lint via ruff; CI with GitHub Actions; run tests on every PR.

Prohibited Actions and Anti-patterns for the AI
- Do not bypass authentication or security checks.
- Do not perform business logic in route handlers.
- Do not generate SQL with string concatenation.
- Do not assume presence of optional fields without validation.
  Recommended Project Structure


  project/
  ├─ app/
  │  ├─ api/
  │  │  └─ v1/
  │  │     ├─ endpoints/
  │  │     │  └─ inspection.py
  │  │     └─ dependencies/
  │  ├─ core/
  │  ├─ db/
  │  │  └─ session.py
  │  ├─ models/
  │  ├─ schemas/
  │  └─ main.py
  ├─ tests/
  ├─ alembic/
  ├─ migrations/
  ├─ requirements.txt
  ├─ Dockerfile
  └─ .env
  Core Engineering Principles


  
    - Single responsibility: endpoints delegate validation, business logic, and data access to dedicated modules.

    - Defensive input validation: strict pydantic schemas for all inputs; fail fast on invalid data.

    - Explicit contracts: clear input/output models, versioned API endpoints, and OpenAPI docs.

    - Auditable outputs: include deterministic identifiers and timestamps in generated reports.

    - Security by default: encrypt secrets, use short-lived tokens, and restrict access to report data by inspector roles.

  
  Code Construction Rules


  
    - Use pydantic models for all API payloads; annotate return types; prefer DTOs for report outputs.

    - Store report generation logic in service modules; keep controllers thin.

    - Adopt SQLAlchemy ORM with explicit session handling; use migrations for schema changes.

    - Generate PDF/HTML reports via a dedicated renderer service and expose via endpoints with deterministic IDs.

    - Include tests for unit, integration, and end-to-end API flows; ensure tests are isolated from external services.

  
  Security and Production Rules


  
    - Do not log secrets or database credentials; read them from environment variables or secret managers.

    - Enable TLS in production; validate JWTs; enforce role-based access to reports.

    - Disable debug endpoints; set proper CORS in production; rotate keys regularly.

  
  Testing Checklist


  
    - Unit tests for data validation and formatting logic.

    - Integration tests for database interactions using a test database.

    - End-to-end API tests using httpx AsyncClient.

    - CI/CD checks: lint, type checks, tests, and security scans.

  
  Common Mistakes to Avoid


  
    - Overloading route handlers with business logic; keep controllers thin.

    - Using raw SQL without parameterization; bypassing the ORM's safety features.

    - Neglecting input validation or poor error handling in report generation.

  

Related implementation resources: AI Use Case for Software Agencies Using Github Copilot To Accelerate Boilerplate Code Generation for New Client Mvps and Localized formatting to override LLM vocabulary biases.




  FAQ


  What is this Cursor Rules Template used for?


  This Cursor Rules Template provides a concrete, copyable .cursorrules configuration for a Python FastAPI + PostgreSQL building inspection report generator. It encodes stack-specific practices for routing, data models, security, and testing to help developers produce consistent, auditable inspection reports.


  Which stack is this template designed for?


  The template targets Python FastAPI with PostgreSQL using SQLAlchemy ORM for building inspection report generation endpoints and a renderer for PDF/HTML outputs.


  How does it enforce security?


  It specifies OAuth2 with JWT tokens, environment-based secrets, role-based access to reports, input validation, and avoidance of credential leakage in logs or responses.


  How do I test the report generation flow?


  Use pytest with httpx to simulate API requests, verify schema validation, render outputs, and confirm that access controls and error paths behave as expected.


  How can I customize for local projects?


  Adapt the project structure to mirror your repository, update database connections, and adjust endpoints and models in app/api/v1, ensuring the cursor rules align with your CI/CD pipeline.