CommissionPro

Business

Original Idea

Sales Commission Calculator A web app that simulates commission plans and generates payout statements.

Product Requirements Document (PRD): CommissionPro

1. Executive Summary

CommissionPro is an enterprise-grade web application designed to eliminate the manual complexity and transparency gaps in sales commission management. By automating the ingestion of sales data and applying a high-performance, rules-based calculation engine, the platform generates real-time payout visibility for sales representatives and audit-ready financial statements for finance teams. CommissionPro replaces error-prone spreadsheets with a scalable, secure, and integrated system of record for sales compensation.

2. Problem Statement

Sales organizations currently suffer from "Shadow Accounting," where sales representatives spend hours tracking commissions in private spreadsheets because they lack trust in manual, opaque finance processes. Finance and Sales Ops teams are bogged down by complex tiered structures, frequent "clawbacks," and the administrative burden of generating hundreds of individual monthly PDF statements. Existing manual processes lead to payout inaccuracies, late payments, and decreased sales morale.

3. Goals & Success Metrics

  • Accuracy: Achieve 99.99% calculation accuracy compared to manual historical audits.
  • Efficiency: Reduce the time required to close monthly commission cycles by 80% (from days to hours).
  • Trust: 90% of Sales Representatives report "high confidence" in payout transparency via the dashboard.
  • Scale: Support processing of 1,000,000+ transactions per hour using the 2026 high-performance stack.

4. User Personas

  • Sales Ops Manager (Sarah): Responsible for building and maintaining commission plans. Needs a flexible UI to define tiers and accelerators without writing code.
  • Finance/Payroll Admin (Frank): Validates final numbers, handles clawbacks, and approves the generation of monthly payout statements.
  • Sales Representative (Riley): Individual contributor who needs to see real-time earnings and "what-if" simulations for their current pipeline.
  • Sales Leadership (VP Victor): Needs high-level views of total commission spend vs. revenue generated to evaluate plan effectiveness.

5. User Stories

  • As Sarah (Sales Ops), I want to build a tiered commission plan (e.g., 5% up to $100k, 10% after) so that I can align rep incentives with company goals.
  • As Frank (Finance), I want to import a CSV of 50,000 deals and have the system flag anomalies so that I can ensure payout integrity.
  • As Riley (Sales Rep), I want to see a real-time dashboard of my earned vs. projected commissions so that I know exactly how much I’ll be paid.
  • As Riley (Sales Rep), I want to run a simulation on a $50k deal to see how it triggers my next accelerator tier.
  • As Victor (VP), I want to see a report on total "commission-to-revenue" ratios to ensure our margin remains healthy.

6. Functional Requirements

6.1 Commission Plan Builder

  • Support for flat rates, tiered structures, and retroactive "cliff" accelerators.
  • Support for "marginal" logic (only the amount above a threshold is taxed at a higher rate).
  • Effective dating for plans (plans can change quarterly).

6.2 Data Ingestion & Sync

  • High-speed CSV upload with row-level validation.
  • Real-time sync with Salesforce and HubSpot via gRPC Pub/Sub APIs.
  • Automated deduplication and status mapping (e.g., "Closed Won" triggers calculation).

6.3 Calculation Engine

  • Asynchronous processing of large datasets using Wasm-powered modules.
  • Support for clawbacks (negative commissions) on returned/canceled goods.
  • Layered simulation engine for "What-If" modeling without affecting production data.

6.4 Reporting & Dashboards

  • Interactive TanStack-powered data grids with group pinning and sparklines.
  • Automated PDF generation for individual monthly payout statements.
  • Audit logs for every manual override or plan change.

7. Technical Requirements

7.1 Tech Stack (January 2026 Standards)

  • Frontend: Next.js v16.1.3 (Turbopack, PPR enabled) with Tailwind CSS v4.1.18 (Rust engine).
  • Data Grid: TanStack Table v8.21.3 (Stable) / v9 transition-ready.
  • Backend: Node.js v24 (LTS) with NestJS v11.1.12 (Express v5 default).
  • Database: PostgreSQL 18 (utilizing Asynchronous I/O and Skip Scans).
  • Rules Engine: GoRules (Wasm-based) for sub-millisecond calculation logic.
  • PDF Engine: Puppeteer + Handlebars for HTML-to-PDF high-fidelity statements.

7.2 Security & Authentication

  • Auth0 Organizations: Multi-tenant isolation for enterprise clients.
  • Auth0 FGA (Fine-Grained Authorization): Relationship-based access control (e.g., Manager can see Reps in their Territory).
  • Database RLS: Row-Level Security as the final fail-safe for financial data isolation.

7.3 Integrations

  • Salesforce: Pub/Sub gRPC API for Change Data Capture (CDC).
  • HubSpot: Journal API (V4) for resumable event streaming.
  • Slack: Bot notifications for "Accelerator Achieved" alerts.

8. Data Model

8.1 User Entity

  • userId (UUIDv7), email (String), role (Enum), tenantId (UUID), managerId (UUID).

8.2 CommissionPlan Entity

  • planId (UUIDv7), name (String), rulesetJson (JSONB - stores tiers/rates), effectiveDate (Date).

8.3 Transaction Entity

  • transactionId (UUIDv7), externalId (CRM ID), amount (Numeric), status (Enum), closeDate (Timestamp).

8.4 PayoutStatement Entity

  • statementId (UUID), userId (UUID), period (String: YYYY-MM), totalEarned (Numeric), pdfUrl (String).

9. API Specification (Partial)

9.1 POST /api/v1/plans

  • Description: Create a new ruleset.
  • Request: { "name": "2026 AE Plan", "tiers": [{ "min": 0, "max": 100000, "rate": 0.05 }] }
  • Response: 201 Created { "planId": "..." }

9.2 POST /api/v1/imports/csv

  • Description: Stream CSV to Postgres via pg-copy-streams.
  • Request: Multipart/form-data (binary stream).
  • Response: 202 Accepted { "jobId": "..." }

9.3 GET /api/v1/analytics/simulate

  • Description: Layered calculation without persistence.
  • Query Params: planId, transactionOverrides (JSON).

10. UI/UX Requirements

  • Optimistic UI: When a rep adjusts a "What-if" slider, dependent commission cells must pulse and update within 100ms.
  • Group Pinning: In the transaction grid, "Deal Name" and "Commission Earned" must remain pinned during horizontal scroll.
  • Faceted Filters: Search bars must include histograms showing the distribution of deal sizes.
  • Accessibility: WCAG 2.1 Level AA compliance, specifically for high-contrast financial tables.

11. Non-Functional Requirements

  • Performance: All dashboard queries must return in < 200ms using PostgreSQL BRIN indexes.
  • Scalability: Horizontal scaling of NestJS workers to handle end-of-quarter spikes.
  • Compliance: SOC2 Type II and GDPR (specifically the "Right to Erasure" for sales data).
  • Availability: 99.95% uptime SLA for monthly payout cycles.

12. Out of Scope

  • Direct Payout Execution: The system will not send ACH/Bank transfers (will export to Payroll/ERP instead).
  • CRM Functionality: We are not building a CRM; we ingest data from existing CRM leaders.
  • Expense Management: Travel and expense reimbursement logic is excluded.

13. Risks & Mitigations

  • Risk: Data drift between Salesforce and CommissionPro.
    • Mitigation: Use HubSpot/SFDC Journal APIs for resumable syncing and weekly "Full-Sync" reconciliations.
  • Risk: Calculation logic complexity.
    • Mitigation: Use PL/Rust for heavy math and exhaustive unit testing via the native node:test runner.
  • Risk: Financial data exposure.
    • Mitigation: Multi-layered security (Auth0 FGA + Next.js DAL + DB RLS).

14. Implementation Tasks

Phase 1: Project Setup & Architecture

  • [ ] Initialize Next.js 16.1.3 project with Tailwind 4.1.18
  • [ ] Configure NestJS 11.1.12 with PostgreSQL 18 connection pool
  • [ ] Set up Auth0 FGA relationship models for Rep/Manager hierarchy
  • [ ] Deploy base infrastructure on Vercel and AWS RDS (Postgres)

Phase 2: Rules Engine & Calculation Core

  • [ ] Implement GoRules Wasm-based calculation module
  • [ ] Create JSONB schema for dynamic tiered plans
  • [ ] Build internal "Pure Function" engine for stateless commission modeling
  • [ ] Develop "Layered Edit" pattern for scenario simulations

Phase 3: Data Ingestion & Integration

  • [ ] Build CSV streaming pipeline using fast-csv-parser and pg-copy-streams
  • [ ] Implement Salesforce CDC listener via gRPC Pub/Sub API
  • [ ] Build HubSpot Journal API poller for resumable deal sync
  • [ ] Add CSV injection protection and sanitization middleware

Phase 4: Frontend & Data Visualization

  • [ ] Build Interactive Grid using TanStack Table v8.21.3
  • [ ] Implement "Optimistic Calculation" pulsing UI for "What-If" sliders
  • [ ] Create Rep Dashboard with sparklines and progress-to-quota bars
  • [ ] Develop Sales Ops Plan Builder UI (drag-and-drop tier logic)

Phase 5: Reporting & Launch

  • [ ] Configure Puppeteer/Handlebars for monthly PDF statement generation
  • [ ] Implement Slack notification service for payout approvals
  • [ ] Perform Load Testing for 1M+ transaction recalculation
  • [ ] Conduct final SOC2 security audit and data penetration test