Shipment Delay Prediction Cursor Rules Template for Courier and Logistics SMEs

Overview

The Cursor rules configuration shown here targets building shipment delay prediction systems for courier and logistics SMEs using a Python stack with FastAPI, PostgreSQL, SQLAlchemy, and ML tooling. This template provides a copyable .cursorrules block you can paste into your project root to guide Cursor AI through architecture, security, data modeling, and ML workflow while honoring production-grade constraints.

When to Use These Cursor Rules

• When implementing a shipment delay predictor for SME couriers using Python and FastAPI.
• When integrating PostgreSQL as the source of truth for shipments, legs, and delay features.
• When combining data engineering, ML model inference, and API endpoints in a single repository.
• When you need consistent security, testing, and deployment workflows baked into Cursor AI guidance.

Copyable .cursorrules Configuration

Framework: python-fastapi
Context: Shipment delay prediction system for courier and logistics SMEs using Python stack with FastAPI, PostgreSQL via SQLAlchemy, and ML pipelines. Provide production-ready code blocks and directory layout.

Framework Role & Context: >
  You are Cursor AI specialized in Python FastAPI based shipment delay systems for SME courier operations. Your outputs must be copyable into the project root as a .cursorrules file.

Code Style and Style Guides: >
  - Python 3.11+
  - PEP8 compliance
  - Type hints and docstrings
  - Prefer Black formatting and isort for imports

Architecture & Directory Rules: >
  - Project root
  - app/
  - app/api/
  - app/core/
  - app/models/
  - app/services/
  - app/db/
  - tests/
  - data/

Authentication & Security Rules: >
  - Use JWT/Bearer tokens for API access
  - Secrets sourced from environment variables; never committed
  - Enforce TLS in production; rotate keys; audit access

Database and ORM patterns: >
  - PostgreSQL as the data store
  - SQLAlchemy declarative models; migrations via Alembic optional
  - Clear separation of data models, schemas, and service layer

Testing & Linting Workflows: >
  - pytest driven tests; fixtures for DB state
  - Pre-commit hooks: black, isort, ruff
  - CI workflow for unit/integration tests and type checks

Prohibited Actions and Anti-patterns for the AI: >
  - Do not call external APIs during code generation
  - Do not leak credentials or secrets in code
  - Do not bypass authentication or authorization checks
  - Do not generate insecure defaults or unsafe data access patterns

Recommended Project Structure

shipment-delay-predictor/
├── app/
│   ├── api/
│   │   └── v1.py
│   ├── core/
│   │   └── config.py
│   ├── models/
│   │   ├── shipment.py
│   │   └── prediction.py
│   ├── services/
│   │   ├── data_ingest.py
│   │   └── model_service.py
│   ├── db/
│   │   ├── base.py
│   │   └── models.py
│   └── main.py
├── tests/
├── data/
├── Dockerfile
├── requirements.txt

Core Engineering Principles

• Separation of concerns between API, data layer, and ML logic.
• Deterministic data handling with explicit schemas and validation.
• Defensive coding: input validation, type hints, and clear error reporting.
• Observability through structured logging, metrics, and traces.
• Reproducibility: versioned models, data schemas, and environment controls.
• Security by default: secrets management, access control, and secure defaults.

Code Construction Rules

• Endpoints in FastAPI must validate inputs with Pydantic models and return typed responses.
• Use SQLAlchemy ORM with a single session per request pattern and proper cleanup.
• Persist ML artifacts via versioned paths; avoid hard-coded file paths in code.
• Feature engineering should be isolated in services with well-defined interfaces.
• All data access must go through a repository-like abstraction to enable testing.
• Do not embed credentials in code; use environment-based configurations.

Security and Production Rules

• Enable TLS and secure HTTP headers in production deployments.
• Rotate API keys and database credentials regularly; audit access logs.
• Validate all inputs and rate-limit API endpoints to mitigate abuse.
• Use prepared statements and parameterized queries to prevent SQL injection.
• Maintain data retention policies and privacy controls for shipment data.

Testing Checklist

• Unit tests for data models, serialization, and utility functions.
• Integration tests covering API endpoints and DB interactions.
• ML pipeline tests for feature generation, model loading, and predictions.
• Security tests for auth flows and input validation.
• End-to-end tests simulating common shipment delay scenarios.

Common Mistakes to Avoid

• Ignoring data drift when updating models; schedule model validation in CI.
• Hard coding file paths or secrets in code; rely on env vars and config files.
• Skipping tests for edge cases like missing data or corrupted inputs.
• Overly permissive DB access in production; follow least privilege.

Related implementation resources: AI Use Case for Delivery Records and Delay Detection and Why authorization checks belong in AI coding instructions for production-grade systems.

FAQ

What is a Cursor Rules Template in this context?

A Cursor Rules Template provides a copyable .cursorrules block and stack-specific guidance to implement a shipment delay prediction system with Cursor AI. It defines architecture, security, and testing expectations so developers can reproduce production-ready results quickly.

Which stack is this template tailored for?

The template targets Python with FastAPI, PostgreSQL via SQLAlchemy, and ML tooling such as scikit-learn. It prescribes project structure, ORM usage, and deployment considerations for courier and logistics SMEs.

How do I integrate the .cursorrules block?

Place the copied block at the project root as .cursorrules and adjust environment-specific values (DB connection string, secrets, and endpoint configs). Cursor AI will follow the rules to produce consistent, secure code and structure.

Can I adapt the template to async endpoints?

Yes. The template supports async CRUD paths with async DB sessions. Update the SQLAlchemy setup and session management to ensure proper concurrency and transaction handling.

What are the recommended testing practices?

Use pytest with fixtures for DB initialization, test each API path, run ML pipeline unit tests, and include CI checks for linting, typing, and security rules.