Commish
Joseph Sidman# Project Specification: Commission & Broker Management System ## Overview This application is a comprehensive platform for insurance agencies or brokerages to track commissions, manage clients/policies, and handle broker (agent) distributions. It features AI-powered statement parsing to automate data entry from complex carrier Excel/PDF sheets. ## Core Functional Requirements ### 1. Statement Processing (AI-Powered) - **Multi-Format Support**: Upload Excel (.xlsx, .csv) or PDF commission statements. - **AI Parsing**: Use Gemini API to extract unstructured data: - Client Name (Auto-mapping to existing clients). - Carrier & Coverage Type (Health, Dental, Medicare, etc.). - Amount (Gross commission). - Pay Date & Service Month. - Policy/Group Number. - Agent Name & Participation/Split Percentages. - **Conflict Resolution**: provide a UI to "Pre-check" data, manually map columns, and fix inconsistencies before final database commit. - **Auto-Classification**: - Medicare entries must be automatically classified into the "Individual" department. - Other entries default to "Group" or follow user-defined client overrides. ### 2. Client & Policy Management - **Client Profiles**: Track revenue (YTD & Lifetime), department (Group vs. Individual), and active status. - **Sync Logic**: When uploading a statement, if a client's department in the statement differs from the existing record (e.g., a Group client now has a Medicare entry), the system should prompt or auto-update the master client record. - **Policies**: Managed as child entities of clients. Each policy holds its own split structure. ### 3. Broker (Agent) Management - **Profiles**: Track agent yields (YTD/Life), base split percentages, and active policy count. - **Commission Splits**: - **Global Base**: Every agent has a default base split (e.g., 70%). - **Policy Overrides**: Ability to set specific participation percentages for an agent on a per-policy basis (e.g., 50/50 split on a specific high-value client). - **Statement Overrides**: If a specific split is listed on an upload sheet, it should update or create a policy-level override for that agent. - **Yield Calculation**: Revenue is calculated based on the participation percentage at the time of entry. ### 4. Financial Reporting - **Multi-Level Grouping**: Aggregate data by Agent, Department, Client, Carrier, or Policy. - **Time-Based Filtering**: Filter by custom date ranges or pre-set periods (YTD, Last Year). - **Metric Definitions**: - **Revenue (Gross)**: The total amount received from the carrier. - **Yield (Net)**: The portion assigned to a specific agent after splits. - **Export**: Ability to generate CSV summaries of filtered reports. ## Data Infrastructure (Firestore) ### `clients` (Collection) - `name` (string) - `department` (string: "Group" | "Individual") - `active` (boolean) - `firstCommissionDate` (string) ### `agents` (Collection) - `name` (string) - `title` (string) - `email` (string) - `splitPercentage` (number: 0-100) - `totalEarned` (number) ### `policies` (Collection) - `policyNumber` (string) - `carrierName` (string) - `coverageType` (string) - `clientId` (string, ref) - `clientName` (string, denormalized) - `status` (string) ### `policies/{policyId}/splits` (Sub-collection) - `agentId` (string, ref) - `percentage` (number) ### `commission_entries` (Collection) - `amount` (number) - `payDate` (string, ISO) - `serviceMonth` (string) - `carrierId` (string, ref) - `clientId` (string, ref) - `policyId` (string, ref) - `agentId` (string, ref) - Primary agent link - `department` (string) ## UI/UX Design Standards - **Aesthetic**: Technical/Modern (Swiss style). Use Indigo and Slate color palettes. - **Navigation**: Sidebar-based navigation with clear sections (Dashboard, Reports, Clients, Agents, Upload). - **Interactions**: - Use `motion` (framer-motion) for all transitions and modal appearances. - "Focus Mode" for detail views (e.g., clicking an agent or client opens a full-height side panel). - High information density with monospace font for financial data. ## Technical Stack - **Framework**: React 18+ with Vite. - **Styling**: Tailwind CSS. - **Database**: Firebase (Firestore). - **AI**: Google GenAI (Gemini 1.5 Pro/Flash). - **Icons**: Lucide React. - **Data Viz**: Recharts (for dashboard trends).
Comments (0)
Sign in to leave a comment
System Requirements
Commish
Introduction
The "Commish" project is designed to serve as a comprehensive internal platform for insurance agencies or brokerages. It aims to streamline the tracking of commissions, management of clients and policies, and handling of broker (agent) distributions. The system leverages AI-powered statement parsing to automate data entry from complex carrier Excel/PDF sheets, enhancing efficiency and accuracy. The focus is on single-user utility, ensuring that the platform is optimized for internal use without the complexities of a commercial product.
System Overview
The Commish system is a robust solution tailored for insurance agencies to manage their commission processes effectively. It integrates AI technology to parse and process commission statements, supports client and policy management, and facilitates broker management. Additionally, it includes financial reporting capabilities and integrates with Salesforce for periodic updates, ensuring seamless data flow and comprehensive client interaction records.
Functional Requirements
- As a User, I should be able to upload Excel (.xlsx, .csv) or PDF commission statements for processing.
- As a User, I should be able to utilize AI parsing to extract unstructured data such as client names, carrier details, and commission amounts.
- As a User, I should be able to resolve conflicts through a UI that allows pre-checking data and manually mapping columns.
- As a User, I should be able to manage client profiles, track revenue, and update client departments based on statement uploads.
- As a User, I should be able to manage broker profiles, track agent yields, and set commission splits.
- As a User, I should be able to generate financial reports with multi-level grouping and time-based filtering.
- As a User, I should be able to export filtered reports as CSV summaries.
- As a User, I should be able to integrate with Salesforce for periodic updates to attach records to commissions.
User Personas
- Admin: Manages the overall system, configures settings, and oversees data integrity.
- Agent: Views personal commission data, manages client interactions, and updates policy details.
- Financial Analyst: Generates reports, analyzes financial data, and ensures compliance with financial regulations.
Visuals Colors and Theme
- primary: #2A4D69 (Deep Teal)
- primary_light: #4B7A94 (Light Teal)
- secondary: #F18D9E (Coral Pink)
- accent: #F2B134 (Golden Yellow)
- highlight: #F28C28 (Amber)
- bg: #F5F7FA (Soft White)
- surface: rgba(255, 255, 255, 0.9) (White)
- text: #2C3E50 (Dark Slate)
- text_muted: #95A5A6 (Muted Gray)
- border: rgba(189, 195, 199, 0.3) (Light Gray)
Signature Design Concept
The homepage of the Commish project will feature an interactive retro terminal aesthetic, where content types itself like a hacker console. Users can interact with the console by typing commands to navigate through different sections of the platform. This concept will be implemented using framer-motion for smooth transitions and animations, providing a unique and engaging experience. The console will be interactive, allowing users to explore functionalities by typing specific commands, creating a nostalgic yet modern interface.
Interaction Model & Motion Direction
The landing page will utilize an "animated" interaction model, with moderate scroll-triggered reveals, hover transitions, and spring physics on interactive elements. Internal pages, such as dashboards and settings, will adopt a "static" interaction model to prioritize clarity and readability.
Non-Functional Requirements
- The system must support periodic data synchronization with Salesforce.
- The platform should handle concurrent user sessions efficiently.
- Data processing should be completed within a reasonable timeframe to ensure timely updates.
Tech Stack
- Frontend: React 18+ with Vite
- Styling: Tailwind CSS
- Database: Firebase (Firestore)
- AI: Google GenAI (Gemini 1.5 Pro/Flash)
- Icons: Lucide React
- Data Viz: Recharts
- Integration: Salesforce for CRM data synchronization
Assumptions and Constraints
- The system assumes periodic data updates from Salesforce are sufficient for operational needs.
- The platform is designed to handle a moderate volume of data and user interactions.
- The AI parsing capabilities are dependent on the accuracy and format of the input statements.
- Basic extraction methods will be used for easily readable formats such as spreadsheets or PDFs with extractable data tables to save costs and improve speed.
Glossary
- AI Parsing: The use of artificial intelligence to extract data from unstructured formats.
- Commission Splits: The division of commission earnings among agents based on predefined percentages.
- CRM: Customer Relationship Management, a system for managing client interactions.
- Firestore: A NoSQL cloud database for storing and syncing data in real-time.
- Animated: A moderate scroll-triggered reveals, hover transitions, and spring physics on interactive elements.
Manage Commissions. Simplify Operations.
AI-powered statement parsing, automated commission tracking, and intelligent conflict resolution — built for modern insurance brokerages that demand accuracy and speed.
Explore the Commission Island
Navigate our interactive 3D island to discover each core module of the winter-commission platform. Click any building to learn more.
Everything You Need to Manage Commissions
From AI-driven statement parsing to Salesforce integration, winter-commission gives your brokerage the tools to track, manage, and grow with confidence.
AI-Powered Parsing
Automatically extract client names, carrier details, and commission amounts from complex Excel and PDF statements using advanced AI.
AutomationCommission Tracking
Track every commission from upload to payout with real-time dashboards, split calculations, and historical trend analysis.
CoreClient Management
Maintain detailed client profiles, track revenue per account, and update departments automatically based on statement uploads.
CRMBroker Management
Manage broker profiles, set commission splits, monitor agent yields, and ensure accurate distribution across your team.
OperationsFinancial Reporting
Generate multi-level grouped reports with time-based filtering. Export filtered summaries as CSV for auditing and compliance.
AnalyticsSalesforce Integration
Sync commission records with Salesforce periodically, attaching interaction history and ensuring seamless CRM data flow.
IntegrationExplore the Island
Each building on the island represents a core module of winter-commission. Hover to discover what powers your brokerage from the inside out.
Drop Excel or PDF commission statements and let AI extract client names, carrier details, and amounts instantly.
Explore→Manage client profiles, track revenue by department, and maintain a comprehensive view of every relationship.
Explore→Set commission splits, track agent yields, and manage broker distributions across your entire agency.
Explore→Generate financial reports with multi-level grouping, time-based filtering, and exportable CSV summaries.
Explore→From Messy Statements to Clean Data
Upload carrier commission statements in any format — PDF, Excel, or CSV. Our AI engine parses unstructured data, extracts client names, policy details, and commission amounts, then maps everything to your schema automatically.
Designed for Every Role
Three distinct workflows tailored for administrators, brokers, and analysts — each with purpose-built tools and views.
Built on Modern, Proven Tools
Every layer of winter-commission is powered by industry-leading technologies — from AI-driven parsing to real-time cloud infrastructure and seamless CRM integration.
Powers the interactive UI with concurrent rendering for seamless commission dashboards and real-time data views.
Lightning-fast build tooling with hot module replacement for rapid development cycles and instant feedback.
Utility-first CSS framework enabling rapid, consistent styling across all commission management interfaces.
Secure cloud backend with Firestore for real-time data sync, authentication, and scalable storage of commission records.
AI-powered statement parsing that extracts client names, carrier details, and commission amounts from unstructured data.
Crisp, consistent icon library providing clean visual cues across navigation, actions, and status indicators.
Composable charting library for financial reports with multi-level grouping, time-based filtering, and live data transitions.
Periodic data synchronization attaches commission records to client interactions for comprehensive CRM integration.
Trusted by Insurance Professionals
See how agencies and brokerages streamline commissions, reduce errors, and save hours every week with winter-commission.
winter-commission completely transformed how we handle carrier statements. What used to take our team 3 days of manual data entry now happens in under 30 minutes with AI parsing. The conflict resolution UI alone saved us from countless errors.
Ready to Streamline Your Commissions?
Join agencies already saving hours each week with AI-powered statement parsing, automated conflict resolution, and real-time financial reporting.
No credit card required·Free 14-day trial·Cancel anytime
No comments yet. Be the first!