Waste Collection Route Optimization Cursor Rules Template

Overview

This Cursor rules template documents how to build a waste collection route optimization tool using a modern Python stack (FastAPI, SQLAlchemy) with PostgreSQL + PostGIS for spatial data. It defines safe AI guidelines, data access rules, and a repeatable project structure so developers can paste the included .cursorrules configuration into their project root and start implementing routing logic with Cursor AI.

Cursor rules template for this stack ensures deterministic outputs, GIS-aware routing, and secure data handling while enabling rapid iteration on routing heuristics, vehicle capacity, time windows, and real-time updates.

When to Use These Cursor Rules

• You need repeatable AI-assisted route planning for municipal waste collection fleets.
• You want strict boundaries on AI-generated code, prompts, and data access to prevent leakage of secrets or schema drift.
• You are integrating spatial queries (PostGIS) with ORM models (SQLAlchemy) in a FastAPI service.
• You need a testable, linted codebase with CI checks for routing algorithms and GIS data handling.
• You require a clear directory structure and provisioning rules for deployment to production environments.

Copyable .cursorrules Configuration

# Cursor Rules Template: Waste Collection Route Optimization

Framework Role & Context:
  You are an AI software architect for a waste collection route optimization stack written in Python 3.11+ using FastAPI, SQLAlchemy, and PostgreSQL + PostGIS. You provide concrete, production-ready guidance with verifiable prompts, and enforce safe AI outputs.

Code Style and Style Guides:
  - Language: Python 3.11+
  - Formatter: Black
  - Linter: Flake8
  - Typing: Optional type hints with mypy where feasible
  - Docstrings: Google style
  - Commit hygiene: meaningful messages; no hard-coded secrets

Architecture & Directory Rules:
  - Project root contains app/, tests/, docs/, scripts/
  - app/main.py: FastAPI instance and route wiring
  - app/models/: SQLAlchemy ORM models
  - app/db/: database session and migrations configuration
  - app/services/: business logic for routing and optimization
  - app/api/: API endpoints and routers
  - tests/: unit and integration tests

Authentication & Security Rules:
  - Use OAuth2PasswordBearer with JWT tokens; enforce token validation on protected endpoints
  - Do not log secrets; read secrets from environment at startup
  - Validate and sanitize all user inputs; restrict path traversal and SQL injection risks

Database and ORM patterns:
  - PostgreSQL with PostGIS for spatial data
  - SQLAlchemy ORM models; use async sessions where possible
  - Spatial queries via PostGIS functions through SQLAlchemy core
  - Alembic for migrations; versioned schema changes

Testing & Linting Workflows:
  - pytest for unit tests; pytest-asyncio for async code
  - tests cover routing logic, spatial queries, and edge cases
  - pre-commit hooks for linting and formatting; CI runs pytest

Prohibited Actions and Anti-patterns:
  - Do not generate raw SQL concatenations; always parameterize queries
  - Do not perform external HTTP calls in unit tests; mock all I/O
  - Do not bypass authentication or return raw exception traces in API responses
  - Do not embed secrets or tokens in code or prompts

Recommended Project Structure

project-root/
├── app/
│   ├── __init__.py
│   ├── main.py
│   ├── api/
│   │   └── router.py
│   ├── models/
│   │   └── route.py
│   ├── services/
│   │   └── routing.py
│   ├── db/
│   │   ├── base.py
│   │   └── session.py
│   ├── core/
│   │   └── config.py
│   ├── schemas/
│   │   └── route_schema.py
│   └── tests/
│       └── test_routing.py
├── tests/
│   └── conftest.py
├── requirements.txt
└── makefile

Core Engineering Principles

• Safety-first AI: enforce guardrails and validate AI outputs before execution
• Deterministic behavior: idempotent operations and reproducible results
• Type-safe interfaces: explicit types and clear API contracts
• GIS-aware data modeling: correct spatial indexes and PostGIS usage
• Auditability: traceable data lineage and change history

Code Construction Rules

• Only Python-based services; avoid non-core languages in core routing logic
• All database access should be parameterized; never concatenate SQL
• Routing algorithms must be modular; pluggable heuristics for distance, time windows, and capacity
• Async I/O must be used for DB calls where supported
• All API endpoints must include authentication and input validation
• Tests must cover edge-case routing scenarios and GIS queries
• Documentation strings and type hints must be present

Security and Production Rules

• Store secrets in environment vars; never hard-code keys
• Use TLS in production; enforce HTTPS endpoints
• Limit rate and input size to protect against abuse
• Back up spatial data and maintain migrations for schema drift

Testing Checklist

• Unit tests for routing heuristics and distance computations
• Integration tests for FastAPI endpoints and DB interactions
• GIS query tests using sample PostGIS data
• CI checks: linting, type checks, and test suite
• Security tests: input validation and auth flow tests

Common Mistakes to Avoid

• Hard-coding city or zone data in logic instead of loading from DB
• Overestimating route optimization without real-world constraints
• Ignoring GIS precision or coordinate systems in spatial queries
• Skipping migrations or direct schema edits in production

Related implementation resources: AI Agent Use Case for Waste Management Firms Using Pickup Logs to Optimize Collection Routes and Environment separation rules for AI-generated apps: practical production-grade patterns.

FAQ

What is a Cursor rules template for waste collection routing?

A Cursor rules template defines stack-specific AI guardrails and implementation guidance to generate, validate, and execute waste collection routing logic. It standardizes architecture, data access, and testing practices so teams can paste a ready-to-run .cursorrules block into their project root for consistent AI-assisted development.

Which stack is this Cursor rules template built for?

This template targets a Python-based stack with FastAPI, SQLAlchemy, PostgreSQL + PostGIS, and Cursor AI for safe, guided AI-assisted development of routing and fleet optimization features.

How do I integrate the .cursorrules block with my project?

Place the copied .cursorrules block in the project root and reference it from your Cursor AI editor. Ensure the project structure matches the recommended layout and that environment variables for DB connections are configured in your deployment environment.

What should I test to ensure reliability?

Unit test routing heuristics, integration tests for API endpoints, and GIS query correctness. Validate data inputs with type checks, mock external services in unit tests, and run full CI with linting and formatting checks.

How do I secure routing data?

Use OAuth2/JWT, encrypt sensitive fields at rest, constrain access by role, and sanitize inputs. Never log secrets or expose private keys through AI prompts or routes.

Can I customize routing heuristics?

Yes. The template is designed to allow plug-in heuristics for distance metrics, time windows, and vehicle capacities. Implement interfaces in app/services and swap in alternative implementations without changing API contracts.