Cursor Rules Template: Python FastAPI Cursor Rules for AI Bookkeeping - Bookkeeping Receipts

Overview


Direct answer: This Cursor Rules Template configures Cursor AI to operate as a Python FastAPI based bookkeeping assistant that OCRs receipts and invoices, categorizes each line item into expenses, and persists results to PostgreSQL with an auditable trail. The template is stack-specific for a modern Python web service that powers automated expense classification.


When to Use These Cursor Rules



  - You are building an AI-powered bookkeeping assistant in Python with FastAPI.

  - OCR results from receipts/invoices must be transformed into structured Expense records.

  - You require auditable, testable rules around category mapping and data validation before persisting data.

  - You need guidance on secure, scalable architecture and CI/CD for a data-centric app.


Copyable .cursorrules Configuration


frameworkRoleAndContext:
  - role: System
  - context: You are Cursor AI configured to design and enforce rules for a Python FastAPI based bookkeeping app.
  - context2: The app reads OCR-extracted receipts and invoices, categorizes expenses, and stores structured records in PostgreSQL with an audit trail.

codeStyleAndGuidelines:
  - style: pep8, black, isort
  - lint: ruff
  - tooling: pre-commit on commit, mypy for type checks

architectureAndDirectoryRules:
  - root: project-root
  - modules:
      accounting_api: src/accounting/api
      accounting_models: src/accounting/models
      expense_service: src/accounting/services/expense_categorization.py
      ocr_service: src/ocr/
  - tests: tests/
  - docker: docker/

authenticationAndSecurity:
  - auth: OAuth2PasswordBearer with JWT
  - secrets: store in env vars; never log tokens
  - inputValidation: strict pydantic models for all inputs

databaseAndOrm:
  - database: PostgreSQL
  - orm: SQLAlchemy
  - models: Expense, Receipt, Category, Vendor
  - migrations: Alembic
  - transactions: use transactional boundaries for all writes

testingAndLinting:
  - unit: pytest with pytest-asyncio for async paths
  - integration: test OCR parsing and DB writes with a test container
  - linting: Ruff and Black checks in CI
  - coverage: require minimum coverage in PRs

prohibitedActionsAndAntiPatterns:
  - Do not call external bank APIs from request handlers
  - Do not bypass input validation or return raw OCR text without sanitization
  - Do not store raw PII beyond retention policy; redact where possible
  - Do not perform long-running OCR calls in web request threads
Recommended Project Structure


project-root/
├── src/
│   ├── accounting/
│   │   ├── api/
│   │   │   └── v1/
│   │   │       ├── routes.py
│   │   │       └── schemas.py
│   │   ├── models/
│   │   │   ├── expense.py
│   │   │   └── receipt.py
│   │   └── services/
│   │       └── expense_categorization.py
│   ├── ocr/
│   │   └── ocr.py
│   └── main.py
├── tests/
├── .pre-commit-config.yaml
└── requirements.txt
Core Engineering Principles



  - Explicit data contracts between OCR, parsing, and persistence layers.

  - Idempotent ingestion of receipts to avoid duplicate expenses.

  - Security by default: validate inputs, sanitize OCR results, and protect credentials.

  - Observability: structured logging, metrics, and tracing for DB writes and OCR calls.

  - Testability: small, deterministic units and clear integration tests for data flows.


Code Construction Rules



  - Models must have strict typing and validation on every field (amount, date, category).

  - Use SQLAlchemy ORM models for Expense, Receipt, and Category with clear relationships.

  - OCR parsing should surface structured fields with fallbacks and validation rules.

  - All API endpoints must be asynchronous where possible and wrapped with proper error handling.

  - Never mutate the input OCR payload after normalization without explicit rule checks.

  - Branching strategy should reflect changes to DB schema and business rules; migrations must be tested before merge.


Security and Production Rules



  - Use OAuth2 with access tokens stored in secure vaults; never log secrets.

  - Validate all OCR-derived data against typing and business rules before persistence.

  - Implement strict rate limiting and IP allowlists for OCR ingestion endpoints.

  - Audit trails: record user actions, token scopes, and data changes with timestamps.

  - Encrypt sensitive fields at rest and in transit; use TLS everywhere.


Testing Checklist



  - Unit tests for OCR parsing rules and category mapping.

  - Integration tests for end-to-end receipt/invoice ingestion to expenses.

  - Contract tests for API request/response schemas.

  - CI should run lint, type checks, unit, and integration tests on PRs.


Common Mistakes to Avoid



  - Overtrusting OCR output without validation and robust fallbacks.

  - Skipping input validation and not handling ambiguous line items.

  - Letting PII linger; failing to implement data retention policies.

  - Ignoring audit trails and transaction boundaries in DB writes.



Related implementation resources: AI Use Case for Accountants Using Quickbooks To Auto-Categorize Business Expenses From Scanned Receipts.




FAQ


What is this Cursor Rules Template used for in Python FastAPI bookkeeping?


This template configures Cursor AI to guide a Python FastAPI based bookkeeping app that OCRs receipts/invoices, categorizes expenses, and stores results in PostgreSQL with an auditable trail.


What stack does this template target?


This template targets a Python FastAPI stack with PostgreSQL and SQLAlchemy. It covers OCR integration, expense categorization, and secure, testable code.


How should expenses be categorized?


Expenses should be categorized by account type, vendor, date, and tax treatment, with a mapping from OCR-detected line items to predefined categories and subcategories.


Where should the .cursorrules block go?


Place the copyable .cursorrules block in the project root as part of your Cursor AI configuration; reference it in your docs and ensure the stack can import or read it at startup.


What are common pitfalls?


Pitfalls include skipping input validation, using unsafe OCR results without verification, storing raw PII without retention policies, and failing to implement proper authentication and access controls.