Cursor Rules Template for Node.js, TypeScript & PostgreSQL: Invoice Reconciliation with Bank Statements

Overview

The Cursor rules configuration for this stack describes how to build an invoice reconciliation service that matches bank statement lines to invoices exported from accounting software. This template targets a Node.js + TypeScript backend with PostgreSQL as the data store, providing a robust, auditable reconciliation flow for finance teams.

Direct Answer

Use these Cursor rules to configure a deterministic, testable reconciliation pipeline that securely ingests bank statements and accounting exports, matches line items to invoices, and emits audit-ready reconciliation results.

When to Use These Cursor Rules

• When building reconciliation services that ingest CSV/OFX bank statements and CSV MT940 accounting exports.
• When you require strict typing, domain-driven design, and auditable, testable reconciliation logic.
• When you need a clean separation of concerns between ingestion, matching, and reporting.

Copyable .cursorrules Configuration

Framework Role & Context:
You are a senior backend engineer tasked with building an bank statement to invoice reconciliation service in Node.js TypeScript with PostgreSQL The system must be robust auditable and testable

Code Style and Style Guides:
Use strict TypeScript ESLint and Prettier Prefer DTOs and a clear service layer

Architecture & Directory Rules:
Follow Clean Architecture with core/domain application usecases infra/persistence and api layers Store SQL in migrations keep domain models pure

Authentication & Security Rules:
JWT based authentication for API endpoints verify tokens on each request Secrets come from environment variables never hard code

Database and ORM patterns:
PostgreSQL with parameterized queries using the pg module Implement a repository layer for data access and a unit of work for transactions

Testing & Linting Workflows:
Unit tests for domain and services integration tests against a test DB CI runs lint type-check and test

Prohibited Actions and Anti-patterns for the AI:
- Do not execute shell commands in production; never log secrets
- Do not bypass auth; do not rely on implicit type coercion; avoid raw string concatenation in queries

Directories:
src/
  api/
    controllers/
    routes/
  app/
  core/
    domain/
    services/
  infra/
    persistence/
    external/
  interfaces/
  tests/
  migrations/

Environment Variables:
DATABASE_URL
JWT_PUBLIC_KEY
JWT_PRIVATE_KEY
BANK_STATEMENT_FORMATS
ACCOUNTING_EXPORT_FORMATS

Recommended Project Structure

src/
  api/
    controllers/
    routes/
  app/
  core/
    domain/
    services/
  infra/
    persistence/
    external/
  interfaces/
  tests/
  migrations/

Core Engineering Principles

• Strong typing and explicit data contracts across ingestion, matching, and reporting.
• Explicit boundaries: domain, application, infrastructure, and API layers.
• Idempotent imports and idempotent reconciliation actions where applicable.
• Auditability: immutable logs, event sourcing where feasible, and detailed trace IDs.
• Defensive programming: input validation, schema validation, and error handling strategies.

Code Construction Rules

• Use a repository pattern to encapsulate data access for bank statements invoices and reconciliations.
• Transactions must wrap multi-step reconciliation operations to ensure atomicity.
• Validate all incoming bank statement rows and accounting exports with a strict schema.
• Do not concatenate SQL strings; use parameterized queries.
• Keep business logic in services persistence concerns in repositories.

Security and Production Rules

• Store secrets in environment variables rotate keys periodically.
• Log redacted events never log full bank statements or invoices.
• Enable rate limiting on API endpoints enforce TLS everywhere.
• Implement thorough input validation and anti tamper checks on uploads.

Testing Checklist

• Unit tests for domain models and reconciliation rules.
• Integration tests covering ingestion matching and export paths.
• End-to-end smoke tests for full reconciliation workflow in a test DB.
• CI: lint type-check unit tests integration tests and migrations run on PRs.

Common Mistakes to Avoid

• Ignoring currency timezone conversions on date fields.
• Assuming CSV formats without header validation.
• Skipping input validation on bank statement imports.
• Mixing domain models with persistence models.

Related implementation resources: AI Agent Use Case for Manufacturing Plants Using Sub-Meter Power Data To Flag Inefficient Machinery Drawing Excess Power and Abstracting DB ops with a clean repository interface.

FAQ

What is a Cursor Rules Template?

A Cursor Rules Template provides a copyable configuration and rules to guide AI generated code and governance for a specific stack, such as Node.js + TypeScript + PostgreSQL for invoice reconciliation.

Which stack does this template target?

Node.js with TypeScript, PostgreSQL, REST API, and JWT based authentication, designed for bank statement ingestion and accounting export reconciliation.

How do I apply the copyable configuration?

Copy the .cursorrules block into the root of your project as .cursorrules and run Cursor AI editor to validate and apply the rules.

What datasets should I prepare for testing?

Prepare sample bank statements in CSV or OFX and accounting exports in CSV MT940 plus a set of invoices for matching tests.