Cursor Rules Template: Environmental Field Reports Generator

Overview

The Cursor rules configuration defines how Cursor AI interacts with the Python + FastAPI + SQLAlchemy + PostGIS stack to generate, validate, and ship environmental field reports. This Cursor Rules Template provides exact constraints, coding standards, and encoding patterns so you can paste a copyable .cursorrules block into your project root and have consistent, safe AI-assisted development.

When to Use These Cursor Rules

• When building GIS-enabled field report applications with Python and FastAPI.
• When you need repeatable AI-assisted code generation across modules (API endpoints, models, and services).
• When integrating PostGIS for spatial data and GeoJSON for interchange formats.
• When enforcing authentication, authorization, and secure data handling in APIs.
• When setting up CI/CD pipelines for data-heavy GIS projects with tests and linting.

Copyable .cursorrules Configuration

Framework Role & Context:
  As the Cursor AI assistant for a Python + FastAPI + SQLAlchemy + PostGIS stack building an environmental field reports generator.

Code Style and Style Guides:
  - Black
  - isort
  - mypy

Architecture & Directory Rules:
  - app/
  - app/api/
  - app/models/
  - app/services/
  - app/db/
  - tests/
  - migrations/

Authentication & Security Rules:
  - OAuth2 with JWT tokens
  - HTTPS in production
  - Do not log credentials or secrets

Database and ORM patterns:
  - SQLAlchemy ORM with declarative models
  - PostGIS geometry/geography types via GeoAlchemy2
  - Alembic migrations for schema management

Testing & Linting Workflows:
  - pytest for unit and integration tests
  - pytest-asyncio for async endpoints
  - pre-commit with black, ruff, isort

Prohibited Actions and Anti-patterns for the AI:
  - Do not compose SQL with string concatenation
  - Do not bypass ORM or perform raw updates without parameters
  - Do not leak credentials in logs or responses
  - Do not mutate global state without clear scope

Recommended Project Structure

environmental-field-reports/
├── app/
│   ├── api/
│   │   └── v1/
│   │       └── reports.py
│   ├── core/
│   │   └── config.py
│   ├── db/
│   │   ├── models.py
│   │   └── session.py
│   ├── models/
│   │   ├── report.py
│   │   └── observation.py
│   ├── services/
│   │   └── report_builder.py
│   ├── main.py
│   └── schemas/
│       └── report_schema.py
├── tests/
│   ├── unit/
│   │   └── test_report.py
│   └── integration/
│       └── test_endpoints.py
├── migrations/
├── alembic.ini
├── requirements.txt

Core Engineering Principles

• Explicit contracts between AI and code writer; keep prompts deterministic.
• Safe data handling; validate and sanitize all inputs and outputs.
• Idempotent operations and deterministic file writes.
• Clear separation of concerns between API, data models, and services.
• Test-driven prompts: codify tests alongside code generation.
• Observability and auditing for AI-generated changes.
• Reproducible builds and dependencies with pinned versions.

Code Construction Rules

• Endpoints should be defined in app/api/v1 with versioned modules; keep routes small and composable.
• Use Pydantic models for request/response validation in FastAPI.
• Define SQLAlchemy ORM models in app/models with clear relationships; avoid lazy-loading surprises.
• Geo fields must use PostGIS types and GeoJSON serialization for external data exchange.
• Database access must go through a scoped session per request; use dependency injection for DAOs.
• All secrets come from environment variables; do not hard-code credentials.
• Write unit tests for business logic and integration tests for endpoints; keep tests fast and deterministic.

Security and Production Rules

• Enable TLS in production; enforce HTTPS for all endpoints.
• Use JWTs with short expiration and refresh tokens; store in Authorization header.
• Sanitize inputs and validate outputs to guard against injection and payload abuse.
• Limit database permissions; use least privilege for the application user.
• Rotate keys, secrets, and database credentials; audit access logs.

Testing Checklist

• Unit tests cover data processing functions and utilities.
• Integration tests validate API endpoints and database interactions.
• Geospatial tests verify PostGIS operations and GeoJSON serialization.
• Linting and type checks pass (Black, Ruff, isort, mypy).
• CI runs tests on push/PR with environment-specific config.

Common Mistakes to Avoid

• Using raw SQL with string concatenation; avoid SQL injection risks.
• Ignoring geospatial data types and CRS handling; always use EPSG-aware operations.
• Coupling business logic to API layer; extract into services for testability.
• Skipping migrations; migrations must track every schema change.
• Neglecting security: expose endpoints without authentication or proper validation.

Related implementation resources: AI Use Case for Software Agencies Using Github Copilot To Accelerate Boilerplate Code Generation for New Client Mvps.

FAQ

What is this Cursor Rules Template designed for?

This Cursor Rules Template guides AI-assisted development of an environmental field reports generator on the Python + FastAPI + SQLAlchemy + PostGIS stack, detailing architecture, styling, security, testing, and anti-patterns for safe AI use.

Which stack is this template tailored to?

It targets a Python-based stack using FastAPI for the API layer, SQLAlchemy for ORM, and PostGIS for geospatial data, oriented toward field report generation and GIS workflows.

How do I paste the .cursorrules into my project?

Copy the code block from the Copyable .cursorrules Configuration section and place it in a .cursorrules file at your project root; Cursor will apply the rules to generated content and code.

Can I adapt this for other GIS data stores?

Yes. While the template emphasizes PostGIS, you can extend to other GIS backends by adjusting ORM models and spatial functions; keep geometry handling consistent with your chosen backend.

Where can I extend tests and CI pipelines?

Extend unit and integration tests in the tests/ directory; configure GitHub Actions or your CI to run tests and linting on push; ensure CI uses the same Python version and dependencies as local development.