Supply Chain Visibility Cursor Rules Template for Cursor AI | Suhas Bhairav

Overview

The Cursor rules configuration is designed for building a Supply Chain Visibility platform that models orders, shipments, suppliers, delays, and risk alerts using Cursor AI. This template targets a Python FastAPI + PostgreSQL stack with SQLAlchemy ORM, providing a copyable .cursorrules configuration you can paste at the project root to accelerate AI-assisted development.

When to Use These Cursor Rules

Model core entities: orders, shipments, and suppliers with clear relationships.
Enforce authentication, authorization, and secure data access for operational data.
Guide AI-generated code to avoid unsafe patterns and architecture drift.
Standardize testing, linting, and CI/CD for a predictable delivery workflow.
Provide a repeatable project structure that maps to production environments.

Copyable .cursorrules Configuration

# Cursor Rules Template for Supply Chain Visibility
# Framework Role & Context
FRAMEWORK = 'Python FastAPI + PostgreSQL (SQLAlchemy)'
ROLE = 'Application Architect for a Python FastAPI service that manages orders, shipments, suppliers, delays, and risk alerts'
CONTEXT = 'Cursor AI assists in building a scalable supply chain visibility platform with real-time risk scoring and event-driven alerts'

# Code Style & Guides
STYLE = 'PEP8, Black, isort'

# Architecture & Directories
ROOT = '/src'
MODULES = ['app','tests','scripts']
APP_STRUCTURE = ['app.api','app.core','app.db','app.models','app.services']

# ORM & Database Patterns
ORM = 'SQLAlchemy (PostgreSQL)'
MODELS = ['Order','Shipment','Supplier','DelayEvent','RiskAlert']
RELATIONSHIPS = 'Order 1..* Shipments; Supplier 1..* Orders; Order with Shipments has delays'

# Authentication & Security
AUTH = 'OAuth2.0 with JWT; RBAC: admin, operator, viewer; token expiry 15m; refresh tokens'

# Data Access & Queries
DATA_ACCESS = 'Parameterized queries; avoid N+1; preload relationships with joins; use pagination'

# Testing & Linting
TESTS = ['pytest','pytest-asyncio','httpx']
LINTERS = ['ruff','black','isort']

# Prohibited Actions & Anti-patterns
DO_NOT = [
  'Embed secrets in code',
  'Use raw string concatenation for queries',
  'Perform blocking DB calls inside async endpoints',
  'Skip migrations; assume existing schema',
  'Ignore input validation; trust client data',
  'Bypass RBAC checks for endpoints'
]

# Cursor AI Actions
ACTIONS = 'Generate data access code with proper typing, tests, and pagination; avoid N+1; log context'

Recommended Project Structure

src/
  app/
    api/
      v1/
        endpoints/
          orders.py
          shipments.py
          suppliers.py
          delays.py
          risk_alerts.py
    core/
      config.py
      security.py
    db/
      base.py
      models.py
      session.py
    services/
      risk_assessment.py
      inventory.py
  tests/
  alembic/

Core Engineering Principles

Explicit data models with clear relationships and migrations.
Idempotent operations and deterministic API behavior.
Strong input validation and explicit typing.
Security by default: auth, RBAC, secrets management.
Observability: structured logs, metrics, and tracing.
CI/CD with automated tests and linting on every PR.
Backward-compatible API design with versioning.
Performance: indexing, pagination, selective loading, and caching where appropriate.

Code Construction Rules

Model endpoints must validate input with Pydantic schemas and emit typed responses.
Use dependency injection for config, DB sessions, and authentication.
Follow a repository pattern: repositories, services, and handlers separated by domain.
Avoid N+1 queries; preload relationships with appropriate joins.
All secret data must be stored in environment variables and loaded via a secure config system.
All code paths must be covered by unit tests and integration tests where applicable.
Do not bypass authentication; never log sensitive fields (PII, tokens).

Security and Production Rules

Use OAuth2 with JWT, verify token scopes; rotate keys regularly.
Enforce TLS, secure cookies, and proper CORS configuration for the API.
Store secrets in a vault or environment-managed store; rotate keys regularly.
Parameterize all queries; avoid raw string interpolation to prevent SQL injection.
Implement rate limiting and robust error handling to avoid DoS vectors.
Enable health checks, logging, and metrics at the edge with minimal exposure of internal state.

Testing Checklist

Unit tests for models and utilities with fixtures for orders, shipments, and suppliers.
Integration tests for API endpoints with authenticated clients.
End-to-end tests for typical workflows from order creation to risk alert emission.
CI checks: lint, type checks, and test coverage thresholds.

Common Mistakes to Avoid

Assuming client data is trustworthy; validate and sanitize all inputs.
Neglecting timezones in datetime fields and reporting.
Missing migrations or relying on runtime schema changes.
Ignoring RBAC and exposing admin endpoints to public access.
Over-fetching data or under-optimizing queries, causing latency.

Related Cursor rules templates

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

FAQ

What is the Cursor Rules Template for this stack?

The Cursor Rules Template provides a ready-to-paste .cursorrules block that configures a Python FastAPI + PostgreSQL stack for a supply chain visibility platform with orders, shipments, suppliers, delays, and risk alerts. It specifies architecture, security, testing, and anti-patterns to guide AI-assisted development.

Which stack does this template target?

It targets a Python FastAPI service using PostgreSQL with SQLAlchemy ORM, designed for a supply chain visibility platform including orders, shipments, suppliers, delays, and risk alerts, with OAuth2 JWT authentication and RBAC.

How do I apply the template to my project?

Save the content as a .cursorrules file at your project root, then use Cursor AI to generate code, ensuring your project structure matches the recommended layout and that you adapt model names to your schema.

How is security handled in this template?

The template enforces OAuth2 with JWT, RBAC, and scoped access. Secrets are not stored in code, and all DB access uses parameterized queries. It also recommends TLS and secure configuration practices for production.

What tests should I run after implementing?

Run unit tests for models and utilities, integration tests for API endpoints, and end-to-end tests for typical workflows. Integrate with CI to run pytest, Ruff, and Black on PRs.

Can I adapt the template for other data domains?

Yes. The template provides a modular approach to adding new domain models (e.g., new entity types) and endpoints while preserving security, testing, and deployment patterns. Adjust models and relationships to fit your domain while keeping the Cursor AI constraints.

Supply Chain Visibility Cursor Rules Template

Target User

Use Cases