Facility Maintenance Analytics Cursor Rules Template

Overview


The Cursor rules configuration provides a Cursor Rules Template for building a facility maintenance analytics tool that processes recurring ticket data. It targets a Python FastAPI stack with PostgreSQL and SQLAlchemy, focusing on data modeling, KPI derivation, and safe AI-assisted code generation. Direct answer: use this template to align data models, API structure, and guardrails for Cursor AI on this stack.


When to Use These Cursor Rules



  - Starting a new analytics service to process recurring maintenance tickets from施設 facilities.

  - Standardizing data models for tickets, work orders, assets, and maintenance calendars.

  - Generating scaffold code, tests, and migrations with AI guidance while enforcing security and quality gates.

  - Auditing data access patterns and ensuring compliant handling of PII and sensitive maintenance data.


Copyable .cursorrules Configuration


# Facility Maintenance Analytics - Cursor Rules for Python FastAPI + PostgreSQL
framework: python-fastapi
language: python
stack: fastapi, sqlalchemy, alembic, pydantic, psycopg2
runtime: python 3.11+
context: Build an analytics tool for recurring maintenance tickets (work orders) in facilities using a PostgreSQL backend. Enable KPI dashboards, trend analysis, and SLA monitoring with Cursor AI guidance while enforcing security and testing disciplines.

frameworkRoleAndContext:
  - System: You are an AI assistant helping developers implement a Facility Maintenance Analytics tool on a Python FastAPI stack.
  - Goals: Design data models for recurring tickets, compute KPIs, generate reports, and automate data validation with safe AI-produced code.

codeStyleAndStyleGuides:
  - Style: PEP8, type hints, black formatting, mypy for types
  - Lint: pytest, flake8, isort

architectureAndDirectoryRules:
  - ProjectRoot: contains app/, tests/, migrations/, configs/
  - app/api/, app/models/, app/services/, app/core/, app/utils/
  - migrations/
  - tests/integration/, tests/unit/

authenticationAndSecurityRules:
  - Auth: OAuth2 with JWT access tokens, HTTPS only, openid-connect compliant
  - Secrets: fetch from environment variables; no hard-coded secrets

databaseAndOrmPatterns:
  - DB: PostgreSQL
  - ORM: SQLAlchemy ORM, Alembic migrations
  - Patterns: models, repositories/services, unit-of-work patterns where needed

testingAndLintingWorkflows:
  - Tests: pytest with DB fixtures and teardown
  - CI: lint, type checks, unit/integration tests on PRs

prohibitedActionsAndAntiPatterns:
  - DoNot: embed raw SQL strings with interpolated values
  - DoNot: bypass authentication in any route
  - DoNot: embed secrets in code or config files

implementationConstraints:
  - Ensure idempotent ticket processing and idempotent migrations in development
  - Respect data privacy; redact PII in analytics dumps when possible
  - Use structured logging with request correlation IDs

notes:
  - Cursor AI should scaffold non-destructive code; review before production deployments
Recommended Project Structure


facility_maintenance_api/
├── app/
│   ├── api/
│   │   ├── v1/
│   │   │   ├── endpoints/
│   │   │   │   └── tickets.py
│   │   │   └── api.py
│   ├── models/
│   │   ├── ticket.py
│   │   │   ├── asset.py
│   │   │   └── index.py
│   ├── schemas/
│   │   └── ticket_schema.py
│   ├── services/
│   │   ├── analytics.py
│   │   └── ticket_processing.py
│   ├── core/
│   │   ├── config.py
│   │   ├── security.py
│   │   └── logging.py
│   ├── db/
│   │   ├── base.py
│   │   └── session.py
│   └── main.py
├── migrations/
├── tests/
│   ├── unit/
│   └── integration/
└── alembic.ini
Core Engineering Principles



  - Explicit contracts between data models, endpoints, and analytics computations.

  - Type-safe code with Pydantic models and MyPy checks.

  - Idempotent operations for data ingestion and migrations.

  - Security by default: authenticated access, encrypted data in transit, and redacted PII where possible.

  - Test-driven scaffolding with unit and integration tests.


Code Construction Rules



  - Define SQLAlchemy models for Ticket, Asset, and MaintenanceEvent with clear relationships.

  - Use Pydantic schemas for API boundaries and analytics output shapes.

  - Isolate analytics logic in app/services to keep endpoints thin.

  - Keep migrations in migrations/ and generate them via Alembic; apply only in non-prod environments during development.

  - Respect environment-driven configuration; never hard-code DB credentials.

  - Ensure endpoints validate inputs and enforce authorization.


Security and Production Rules



  - Use OAuth2 with JWTs; validate scopes on all endpoints.

  - Enforce HTTPS, security headers, and CSRF protection for state-changing operations.

  - Mask or redact PII in analytics outputs; restrict data exposure by role.

  - Implement rate limiting and audit logging for critical APIs.

  - Separate read/write concerns; use prepared statements to prevent SQL injection.


Testing Checklist



  - Unit tests for models, utilities, and services with in-memory DB fixtures.

  - Integration tests for API endpoints against a test PostgreSQL database.

  - End-to-end tests simulating recurring ticket ingestion and KPI computation.

  - Linting, typing checks, and test coverage thresholds in CI.


Common Mistakes to Avoid



  - Ignoring data privacy when exporting analytics; always redact PII in test data and samples.

  - Overexposing internal APIs; enforce correct authorization for analytics endpoints.

  - Coupling analytics logic to ORM specifics; keep business rules in services layer.

  - Neglecting migrations in development leading to drift between models and DB schema.



Related implementation resources: AI Use Case for Geotechnical Firms Using Core Sample Records To Predict Soil Stability for Heavy Foundation Building and Threat Auditing AI Systems: Simulating Malicious User Inputs to Validate Defenses.




FAQ


What is the purpose of this Cursor Rules Template?


This Cursor Rules Template provides a structured set of guidelines and a copyable .cursorrules block to help developers implement a facility maintenance analytics tool on a Python FastAPI + PostgreSQL stack. It defines architecture, security constraints, testing, and anti-patterns to guide Cursor AI in safe, stack-specific code generation.


Which stack does this template target?


The template targets a Python FastAPI backend with SQLAlchemy ORM, PostgreSQL database, Pydantic models, and OAuth2/JWT authentication. It emphasizes analytic data workflows from recurring tickets, KPI calculations, and secure data access for operations and dashboards.


What does the Copyable .cursorrules block include?


The block specifies framework, roles, architecture, security, testing, and anti-pattern rules, plus a recommended project structure. It ensures idempotent processing, data privacy, and safe AI generation practices suitable for the facility maintenance analytics domain.


How should the project structure be organized?


The structure places API, models, and services under app/, migrations for schema changes, and tests under tests/. It supports scalable analytics and easy testing without coupling to non-essential technologies.


What security considerations are emphasized?


Security focuses on JWT-based authentication, HTTPS enforcement, secret management via environment variables, role-based access control, and restricted data exposure in analytics outputs.


What tests should be implemented?


Unit tests for models and utilities, integration tests for API endpoints, and end-to-end tests of recurring ticket ingestion and KPI computation. CI should run linting, type checks, and coverage gates.