Cursor Rules Template: Customs Document Validation Tools for Import/Export with Cursor AI

Overview


Cursor rules configuration for building customs document validation tools using Python FastAPI and PostgreSQL with Cursor AI support. This template defines a secure, testable backend that validates import/export documents (invoices, packing lists, Bills of Lading, certificates of origin) and enforces HS codes and tariffs. It provides a concrete, copyable .cursorrules block you can paste into your project root.


When to Use These Cursor Rules



  - When implementing backend validation for customs documents in an import/export workflow.

  - When you need a typed API surface with FastAPI, SQLAlchemy, and JWT authentication.

  - When you require repeatable, audit-friendly data validation and easy CI integration.

  - When you want Cursor AI to guide standards for data extraction and transformation from PDFs or scans.


Copyable .cursorrules Configuration


Copy this exact block into your project root as .cursorrules. It includes Framework Role & Context, Code Style, Architecture, Security, ORM usage, Testing, and Anti-pattern rules.


.cursorrules
Framework: Python FastAPI
Runtime: Python 3.11+
Context: You are a backend software engineer building an import/export customs validation service with Cursor AI.
Role: Backend API for document validation; ensure deterministic, auditable validation pipelines.

Code Style and Style Guides
— Enforce Black formatting; isort for imports; mypy for type hints; flake8/ruff for linting.
— Use Pydantic models for request/response validation; strict typing where possible.
— Apply request timeouts and structured error handling; never return raw exceptions to clients.

Architecture & Directory Rules
— Use a clean layered API: api -> services -> models -> db -> schemas.
— Place business logic in services; keep endpoints thin.
— Migrations with Alembic; models anchored to SQLAlchemy ORM.
— Do not rely on global mutable state; use dependency injection for config and DB sessions.

Authentication & Security Rules
— OAuth2 with JWT access tokens; store only salted hashes for credentials.
— Enforce TTLs on tokens; implement token revocation strategy.
— Validate input strictly; forbid directory traversal and arbitrary file reads.
— Do not log sensitive data; mask PII in logs.

Database and ORM patterns
— PostgreSQL with SQLAlchemy ORM; use declarative base; per-request session management.
— Use Alembic for migrations; seed permissions and HS code reference data via migrations.
— Model validation via Pydantic schemas; map to ORM models with consistent naming.

Testing & Linting Workflows
— PyTest + pytest-asyncio for async endpoints; use factory patterns for test data.
— Include unit tests for validators, integration tests for routes, and end-to-end checks for document flow.
— CI: run lint, type checks, unit/integration tests on push; fail on warnings treated as errors.

Prohibited Actions and Anti-patterns for the AI
— Do not perform network calls from within validation logic except to internal services.
— Do not access local files outside the project structure; avoid arbitrary FS access in validation.
— Do not generate or execute executable code at runtime from user input.
— Do not bypass authentication or bypass schema validation for performance.
Recommended Project Structure


project-root/
├── app/
│   ├── main.py
│   ├── api/
│   │   └── v1/
│   │       ├── endpoints/
│   │       │   └── customs.py
│   │       └── dependencies/
│   ├── core/
│   │   ├── config.py
│   │   └── security.py
│   ├── db/
│   │   ├── base.py
│   │   └── session.py
│   ├── models/
│   │   └── document.py
│   ├── schemas/
│   │   └── document.py
│   ├── services/
│   │   └── validator.py
│   └── validators/
│       └── customs.py
├── migrations/
├── tests/
Core Engineering Principles



  - Clear API contracts with strict typing and validated data models.

  - Defensive, explicit code; minimize implicit behavior and hidden side effects.

  - Idempotent operations for document validation to support retries and replays.

  - Observability: structured logging, metrics, and tracing for validation steps.

  - Security-first design: least privilege, token-based auth, and validation at the boundary.

  - Cursor AI-guided rules with safety checks and auditable decisions.


Code Construction Rules



  - Endpoints must be async; use Pydantic models for OpenAPI schemas and request bodies.

  - Database access via repositories; avoid raw SQL in business logic.

  - All secrets sourced from environment variables; never hard-code credentials.

  - Validation logic must be deterministic and testable; avoid non-deterministic calls.

  - Use migrations for schema changes; seed reference data with migrations.

  - Maintain separation of concerns: API, services, models, and validators.


Security and Production Rules



  - Use HTTPS, TLS, and secure cookie attributes if applicable in web layer.

  - Enforce OAuth2 with JWT access tokens; implement token rotation and revocation.

  - Validate all inputs; reject unexpected fields; apply strict content-type checks.

  - Rate limiting and request quotas to prevent abuse of document validation endpoints.

  - Audit logs for document validation events; redact PII where necessary.


Testing Checklist



  - Unit tests for each validator rule and model serialization.

  - Integration tests for API endpoints with a test DB (in-memory or CI-provisioned).

  - End-to-end tests simulating document upload, extraction, and validation flow.

  - Static analysis and type checks in CI; run linting with strict rules.

  - Security tests: input validation, token auth, and misconfiguration checks.


Common Mistakes to Avoid



  - Relying on real-time remote data during validation; use cached/hosted reference data.

  - Skipping migrations or seeding when schema changes occur.

  - Exposing internal debug information in production responses.

  - Overly permissive auth or leaking credentials through logs.



Related implementation resources: AI Use Case for Import-Export Small Businesses Using Pdfs To Translate and Verify Compliance On Customs Documentation and Hardening the API gateway for self-hosted LLM deployments: production-grade security patterns.




FAQ


What is this Cursor Rules Template for customs document validation?


This template provides a complete, copyable .cursorrules configuration for building a Python FastAPI backend to validate import/export customs documents, including authentication, ORM usage, and testing workflows with Cursor AI.


Which stack is this template designed for?


The template targets Python FastAPI with PostgreSQL via SQLAlchemy, Pydantic models, Alembic migrations, and JWT-based authentication, designed to work with Cursor AI guidance and safety constraints.


How do I use the .cursorrules block?


Copy the block into the root of your project as .cursorrules and tailor the configuration to your environment, including database URLs, token settings, and allowed origins. Cursor AI will guide coding and structure within the constraints defined here.


What should the project structure look like?


The recommended structure keeps api, core, services, models, schemas, and validators separate under app/ to ensure clean layering and testability for document validation rules.


How is security enforced in production?


Security is enforced via OAuth2 JWTs, environment-based config, input validation, rate limiting, and audit logging of validation events; no sensitive data is logged or exposed in errors.


How do I test and validate the Cursor rules locally?


Use unit tests for validators, integration tests for endpoints with a test database, and CI with linting, type checks, and a security test suite to validate the entire flow from document intake to validation verdict.