Cursor Rules Template for Django Freelancer Finance App | Suhas Bhairav

Overview

The Cursor rules configuration described here is tailored for a Django-based freelancer finance app that manages invoices, expenses, tax estimates, clients, and payment reminders. It provides a copyable .cursorrules block you can paste into your project root to guide Cursor AI in building and validating code and configurations for this stack.

When to Use These Cursor Rules

Starting a Django + PostgreSQL project for freelancer finances with invoices and payments.
Enforcing money handling, client management, and reminder workflows across models and APIs.
Onboarding new developers to ensure architecture, security, and testing standards are followed.

Copyable .cursorrules Configuration

framework: Django
version: 4.x
language: Python
runtime: Python 3.11

# Role & Context
role: You are Cursor, an AI assistant specialized in building Django apps for freelancer finance management.
context: Project Freelancer Finance with core entities: Invoice, Expense, TaxEstimate, Client, PaymentReminder.

# Code Style and Style Guides
styleGuides:
  - PEP8, Black, isort
  - type hints where appropriate
  - docstrings for public APIs

# Architecture & Directory Rules
apps:
  - invoices
  - expenses
  - clients
  - tax_estimates
  - reminders
structure:
  projectRoot: /src/freelancer-finance
  djangoAppsDir: /src/freelancer-finance/apps
migrationsDir: migrations/
directoryRules:
  - Keep models, views, serializers, and urls within their Django app directories
  - Migrations must be managed via Django, not manually altered in production

# Authentication & Security Rules
auth:
  - Use Django authentication for UI and REST API tokens for API access
  - CSRF protection enabled; HTTPS in production; secret keys from environment
  - Password hashing with Argon2 or PBKDF2 with per-user salts

# Database and ORM patterns
database:
  engine: PostgreSQL
  moneyType: decimal.Decimal
  currencyField: CharField(3)
  models:
    Invoice:
      fields: [id, client FK, amount, due_date, status, issue_date, currency]
    Expense:
      fields: [id, invoice FK nullable, amount, category, date, receipt]
    TaxEstimate:
      fields: [id, client FK, year, estimated_tax, currency]
    PaymentReminder:
      fields: [id, invoice FK, due_status, remind_at]

# Testing & Linting Workflows
testing:
  - pytest-django for tests
  - pytest-cov for coverage
  - factory_boy for test data
linting:
  - black, isort, flake8

# Prohibited Actions and Anti-patterns for the AI
antiPatterns:
  - Do not write raw SQL with string concatenation
  - Do not bypass Django ORM for critical writes
  - Do not store secrets in code or commit them
  - Do not rely on client-side validation as the sole validation

Recommended Project Structure

freelancer-finance/
├── manage.py
├── requirements.txt
├── src/
│   └── freelancer_finance/
│       ├── settings.py
│       ├── urls.py
│       └── wsgi.py
├── apps/
│   ├── clients/
│   │   ├── models.py
│   │   ├── views.py
│   │   └── urls.py
│   ├── invoices/
│   │   ├── models.py
│   │   ├── views.py
│   │   └── urls.py
│   ├── expenses/
│   │   ├── models.py
│   │   ├── views.py
│   │   └── urls.py
│   ├── tax_estimates/
│   │   ├── models.py
│   │   ├── views.py
│   │   └── urls.py
│   └── reminders/
│       ├── models.py
│       ├── views.py
│       └── urls.py
├── templates/
├── static/
└── tests/

Core Engineering Principles

Explicit domain modeling for Client, Invoice, Expense, TaxEstimate, and PaymentReminder.
Data integrity via Django ORM constraints and decimal money handling.
Security by design: authentication, authorization, and secrets management.
Testability with unit and integration tests and deterministic interfaces.
Clear module boundaries and reusable components per app.
Observability: structured logging and CI-friendly test hooks.

Code Construction Rules

Define Django models with precise fields and relations: Client, Invoice, Expense, TaxEstimate, PaymentReminder.
Money fields use decimal.Decimal; currency uses a 3-letter code field.
Validate input at both model and serializer levels; use clean methods for domain rules.
Invoices should use a small enum for status with explicit choices.
Use Django REST Framework serializers for API endpoints; enable pagination and proper permissions.
Unit tests for models and serializers; integration tests for invoice flows (create, reminders, tax estimates).
Do not bypass the ORM or apply unsafe raw SQL for core operations.

Security and Production Rules

Enforce HTTPS and CSRF protection; secure cookies and session handling.
Secrets must live in environment variables; never commit credentials.
Use Django's authentication with role-based access to sensitive data.
Implement rate limiting for reminder generation and batch tasks.
Ensure migrations run in CI before production deployment; monitor for drift.

Testing Checklist

Unit tests for models and domain logic; serializer tests for API shapes.
Integration tests for end-to-end flows: client, invoice, expense, tax estimate, reminder.
End-to-end tests with mocks for external services (email/SMS reminders, payment gateways).
CI checks: lint, type checks, and test coverage thresholds.

Common Mistakes to Avoid

Relying on client-side validation as the sole source of truth for financial data.
Storing money as float types; use decimal with currency codes.
Monolithic app without clear domain boundaries; fail to modularize by invoices, clients, etc.
Neglecting migrations and backwards compatibility in evolving schemas.

Related Cursor rules templates

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

FAQ

What is the Cursor Rules Template for Django freelancer finance app?

This Cursor Rules Template provides copyable instructions for building a Django-based freelancer finance app with invoices, expenses, tax estimates, clients and reminders. Paste the block into a .cursorrules file to guide Cursor AI in code, tests, and deployment patterns specific to this stack.

Which Django patterns are enforced by the rules?

The rules enforce Django ORM-based models, Money handling via decimal fields, related FK models (Client, Invoice, Expense, TaxEstimate, PaymentReminder), DRF serializers, and a test-driven API design with proper security and CI guidance.

How is money represented and validated?

Money is stored as decimal.Decimal with a 3-letter ISO currency code. All arithmetic uses Decimal with explicit context to avoid rounding errors and maintain precision in invoices and tax estimates.

How are reminders and tax estimates modeled?

Payment reminders link to invoices; tax estimates are linked to clients with year and currency fields. The rules include scheduling logic, validation tests, and end-to-end scenarios for reminder sending and tax calculation.

What security practices are required?

HTTPS in production, CSRF protection, environment-based secrets, and Django authentication with proper data access controls. API endpoints should enforce permissions and rate limits in production.

Where should I place the Cursor Rules file?

Place the .cursorrules file at the Django project root or a dedicated config folder, so Cursor AI can load rules during code generation and validation.

Cursor Rules Template: Django Freelancer Finance App

Target User

Use Cases