Cursor Rules Template: Maintenance Management System with Cursor AI

Overview

Direct answer: This Cursor Rules Template enables building a complete maintenance management system using FastAPI with SQLAlchemy and PostgreSQL. It provides a copyable .cursorrules block and strict rules for architecture, security, testing, and Cursor AI usage, focused on work orders, spare parts, technicians, schedules, and analytics.

When to Use These Cursor Rules

When starting a new maintenance management project with Cursor AI integration for scalable work orders, parts inventory, and analytics.
When you need a standardized project structure that enforces security, testing, and deployment best practices in Cursor AI workflows.
When adopting FastAPI + SQLAlchemy as the backend stack and PostgreSQL as the data store.

Copyable .cursorrules Configuration

Framework: Python
Stack: FastAPI + SQLAlchemy + PostgreSQL
Role: Software Engineer
Context: Build a maintenance management system with work orders, spare parts, technicians, schedules, and analytics using Cursor AI.

CodeStyle: PEP8, Black
Architecture: app/api, app/core, app/models, app/db, app/services, app/schemas, tests
DirectoryRules: enforce modular packages with clear boundaries

Authentication & Security: JWT/OAuth2, password hashing, secrets from environment variables

Database & ORM: PostgreSQL with SQLAlchemy ORM; migrations with Alembic; define models for WorkOrder, SparePart, Technician, Schedule, Analytics

Testing & Linting Workflows: PyTest with pytest-asyncio; flake8 or Ruff; pre-commit hooks

Prohibited Actions & Anti-patterns: Do not eval user input; Do not embed secrets in code; Do not bypass migrations; Do not use raw SQL in business logic; Do not access filesystem in request handlers.

Notes: The rules enforce safe AI-assisted development and reproducible scaffolding for the stack.

Recommended Project Structure

.
├── app
│   ├── api
│   │   ├── v1
│   │   │   ├── endpoints
│   │   │   │   ├── maintenance.py
│   │   │   │   ├── inventory.py
│   │   │   │   └── analytics.py
│   ├── core
│   │   ├── config.py
│   │   ├── security.py
│   │   └── logging.py
│   ├── db
│   │   ├── base.py
│   │   └── session.py
│   ├── models
│   │   ├── work_order.py
│   │   ├── spare_part.py
│   │   ├── technician.py
│   │   └── schedule.py
│   ├── schemas
│   │   ├── work_order_schema.py
│   │   └── analytics_schema.py
│   ├── services
│   │   ├── maintenance_service.py
│   │   └── analytics_service.py
│   └── main.py
├── alembic
│   ├── versions
│   └── env.py
├── tests
│   ├── unit
│   └── integration
└── .github
    └── workflows
        └── ci.yml

Core Engineering Principles

Encapsulate domain logic in small, testable services with clear interfaces.
Strict separation of concerns: API, business logic, data access, and analytics layers.
Type safety and input validation with Pydantic models and SQLAlchemy ORM mappings.
Explicit dependencies and environment-driven configuration for production parity.
Security first: do not leak secrets; use JWT/OAuth2; enforce proper access controls.

Code Construction Rules

Define models for WorkOrder, SparePart, Technician, Schedule, and Analytics with clear FK relationships.
API endpoints under app/api/v1 for maintenance, inventory, and analytics; use FastAPI routers.
Use Alembic for migrations; keep migration scripts versioned and reviewable.
Use dependency injection to provide DB sessions; no global sessions in request handlers.
Validation and serialization with Pydantic; ensure response models do not expose sensitive fields.
Do not hard-code credentials; read from environment or secret manager.

Security and Production Rules

Encrypt secrets at rest and in transit; use TLS; rotate keys regularly.
Enforce RBAC: technicians, supervisors, and admins have scoped permissions.
Input validation to prevent SQL injection; use ORM query builders; avoid raw SQL in business logic.
Audit logging for changes to work orders and parts inventory.
CI/CD with tests; containerize with minimal base images; use health checks and monitoring.

Testing Checklist

Unit tests for domain models and service logic.
Integration tests for endpoints and DB interactions with a test database.
Migration tests to verify Alembic scripts apply and rollback cleanly.
Static analysis with Ruff/Flake8; formatting with Black; lint in CI.
Security tests for authentication and RBAC flows.

Common Mistakes to Avoid

Overloading endpoints with business logic; prefer services and repositories.
Hard-coded secrets or credentials in code or config.
Ignoring migrations; bypassing schema changes can cause data loss.
Unsecured admin endpoints or missing RBAC checks.
Using raw SQL in services without proper parameterization.

Related Cursor rules templates

Explore adjacent Cursor rules templates for similar stacks, workflows, and production constraints.

FAQ

Is this Cursor Rules Template tailored for a FastAPI + SQLAlchemy stack?

Yes. The template targets a Python FastAPI backend with SQLAlchemy ORM on PostgreSQL, including migration tooling and Cursor AI rules to guide development and prevent drift.

How do I paste the .cursorrules block into my project?

Copy the block from the Copyable .cursorrules Configuration section and paste it at the repository root as .cursorrules. Ensure your project structure matches the recommended layout and run Cursor to scaffold or validate the setup.

Does it cover security and production readiness?

Yes. The rules enforce JWT/OAuth2 authentication, environment-based secrets, RBAC, and auditing; production deployment should follow TLS, secret rotation, and monitoring guidelines.

What if I use a different database than PostgreSQL?

The template assumes PostgreSQL; for other databases, adjust the ORM configuration, dialect, and migrations while preserving the architecture and security rules.

Can I customize analytics and scheduling rules?

Yes. The template provides analytics and scheduling modules as part of the architecture; Cursor AI can tailor thresholds, dashboards, and alerting based on your data model.

Target User

Use Cases