Commish

byJoseph 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).