finance

Finance

Mission

Build financial systems following best practices for accuracy, compliance, and auditability. Covers payment integration, billing, invoicing, tax calculation, financial reporting, and ledger patterns.

First Action

Read docs/ARCHITECTURE.md if it exists, then scan the project for existing financial modules, payment providers, or currency handling.

Core Principles

Security First (Mandatory)

• NEVER trust user input - validate and sanitize ALL inputs on server side
• ALWAYS use parameterized queries - never string concatenation for SQL/NoSQL
• NEVER expose sensitive data (tokens, passwords, PII) in logs, URLs, or error messages
• ALWAYS implement rate limiting on public endpoints
• Use HTTPS everywhere, set secure headers (CSP, HSTS, X-Frame-Options)
• Follow OWASP Top 10 - prevent XSS, CSRF, injection, broken auth, etc.
• Secrets in environment variables only - never hardcode

Performance First (Mandatory)

• Use your framework's recommended data fetching and caching strategy (check docs/ARCHITECTURE.md if available)
• Configure appropriate cache TTLs based on data freshness needs
• Use pagination patterns that avoid loading flickers (keep previous data visible)
• Implement optimistic updates for mutations when UX benefits
• Lazy load routes, components, and heavy dependencies
• Avoid N+1 queries - batch requests, use proper data loading patterns

Code Language (Mandatory)

• ALWAYS write code (variables, functions, comments, commits) in English
• Only use other languages if explicitly requested by the user
• User-facing text (UI labels, messages) should match project's i18n strategy

Scope Detection

• Payment: user wants payment integration (Stripe, PayPal, gateway) → Payment mode
• Billing: user wants billing, invoicing, or subscription management → Billing mode
• Reporting: user wants financial reports, dashboards, or ledger views → Reporting mode

---

Payment Mode

Workflow

1. Ask: payment provider (Stripe, PayPal, Square, etc.), payment types (one-time, subscription, metered), currency requirements
2. Analyze existing project structure and identify where payment logic should live
3. Create payment service layer:
   • Payment types/contracts (amounts in smallest currency unit - cents, not dollars)
   • Payment service (API calls to provider)
   • Payment adapter (provider response → app contract)
   • Webhook handler for async events (payment succeeded, failed, refunded)
4. Create checkout flow:
   • Payment intent/session creation
   • Client-side payment form integration
   • Confirmation handling and error states
5. Implement idempotency keys for all payment mutations
6. Add proper error handling with user-friendly messages
7. Validate with type checking