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
Project Tasks25
Implement Navbar for Landing
As a frontend developer, implement the Navbar section for the Landing page. This is a shared component (sections/Navbar.jsx) that may be reused across pages. Build a sticky motion.nav using framer-motion with scroll-driven backdrop blur (useTransform on scrollY [0,120,180] → bgOpacity, blurVal, shadowOpacity), animated SVG logo with path-draw on mount (motion.path pathLength 0→1), NAV_LINKS array with linkHoverVariants (scale 1→1.04), and a hamburger button with topLineVariants/midLineVariants/botLineVariants animating to an X on open. Mobile drawer uses AnimatePresence and locks body scroll via useEffect on mobileOpen state.
Configure Firebase Firestore
Initialize Firebase project, configure Firestore security rules for collections (clients, agents, policies, commission_entries), set up Firebase SDK in the React app with environment variables, and create Firestore indexes for common queries (by agentId, clientId, payDate, department). Note: frontend Dashboard, Clients, Agents, Reports, Profile sections depend on this.
Build File Upload Parse Utilities
Implement client-side file parsing utilities for statement uploads: (1) xlsx/csv parser using SheetJS (xlsx library) to convert spreadsheet data to JSON row arrays, (2) PDF text extraction using pdf-parse or pdfjs-dist to extract raw text for Gemini ingestion. Expose a unified parseFile(file: File) function returning { format, rawContent, rows? }. Validate file type and size (max 10MB). These utilities feed directly into the Gemini AI parse service. Note: Upload page sections depend on this.
Set Up Tailwind Theme & Design System
Configure Tailwind CSS with the project's design tokens in tailwind.config.js: extend colors with primary (#1A3D6C), primary_light (#3F6BAA), secondary (#D94E1F), accent (#F2C94C), highlight (#F2994A), bg (#F7F9FC), surface, text, text_muted, border. Add custom font (Inter + monospace for financial data). Create a global CSS file (index.css or theme.css) with CSS custom properties matching the SRD palette. Build reusable Tailwind component classes: .btn-primary, .btn-secondary, .card-surface, .focus-panel, .data-table. This underpins all page section styling.
Configure Environment Variables & Vite
Set up .env and .env.example files with all required environment variables: VITE_FIREBASE_API_KEY, VITE_FIREBASE_AUTH_DOMAIN, VITE_FIREBASE_PROJECT_ID, VITE_FIREBASE_STORAGE_BUCKET, VITE_FIREBASE_MESSAGING_SENDER_ID, VITE_FIREBASE_APP_ID, VITE_GEMINI_API_KEY, VITE_SALESFORCE_CLIENT_ID, VITE_SALESFORCE_CLIENT_SECRET, VITE_SALESFORCE_INSTANCE_URL. Configure vite.config.js with path aliases (@/components, @/services, @/contexts), and ensure environment variables are properly typed in a vite-env.d.ts. Document all variables in .env.example with placeholder values.
Implement LandingHero for Landing
As a frontend developer, implement the LandingHero section using @react-three/fiber Canvas with a full 3D island scene. Build IslandBase (cylinder + cone + circle geometry with flatShading colors #4a7c59/#8b7355/#6db86b), Building components (boxGeometry + coneGeometry roof + planeGeometry window glow using #F2C94C, hover state with emissiveIntensity 0.4, spring-lerped scale via useFrame), Trees (cone + cylinder meshes), and Clouds (SphereGeometry with MeshDistortMaterial from @react-three/drei). The island group rotates at 0.08 rad/s via useFrame clock. Wrap canvas in a motion.div with useInView for headline/subheadline fade-in animations. The island scene uses Float from drei for gentle bobbing.
Implement IslandShowcase for Landing
As a frontend developer, implement the IslandShowcase section — the most complex 3D interactive section. Build a @react-three/fiber Canvas with 4 BUILDINGS config objects (Upload Center, Client Hub, Broker Management, Reports & Analytics) each with id, color, position, height, href, description, and features array. Each Building uses RoundedBox + MeshWobbleMaterial from @react-three/drei, emissive glow refs animated via useFrame delta lerp (targetEmissive/currentEmissive refs), and OrbitControls for user camera rotation. On 3D building select/hover, render a 2D AnimatePresence panel (motion.div) with building label, description, features list, and CTA link. Manage isSelected/isHovered state per building via onSelect/onHover/onUnhover callbacks. Uses useMemo for THREE.Color instances and useCallback for event handlers.
Implement LandingFeatures for Landing
As a frontend developer, implement the LandingFeatures section with a 6-card features grid. Import BrainCircuit, TrendingUp, Users, Building2, BarChart3, Cloud from lucide-react. Render the features array (id, icon, title, description, tag, variant) using containerVariants (staggerChildren 0.1, delayChildren 0.15) and cardVariants (opacity 0→1, y 40→0, duration 0.55, cubic-bezier easing). Header uses headerVariants (opacity 0→1, y 24→0). Include two lf-parallax-mid decorative shape divs (lf-deco-shape--1/2/3) that shift via CSS var(--scroll) at -0.4px multiplier for the parallax midground layer.
Implement BuildingsHighlight for Landing
As a frontend developer, implement the BuildingsHighlight section with 4 FlipCard components for Upload, Clients, Brokers, and Reports. Each FlipCard uses useInView (margin '-60px', once true) for scroll-triggered entry animation (opacity 0→1, y 40→0 with staggered delay index*0.12). Card flip is driven by isFlipped state toggled on mouseEnter/mouseLeave and tap, using motion.div animate={{ rotateY: isFlipped ? 180 : 0 }} with duration 0.5. Mouse parallax text offset tracked via handleMouseMove computing centerX/centerY offsets at 0.08 multiplier stored in textOffset state. Imports Upload, Users, Briefcase, BarChart3, RotateCcw from lucide-react. Front face shows icon + name, back face shows description + href link.
Implement AICapabilities for Landing
As a frontend developer, implement the AICapabilities section with an interactive before/after slider. Use useSpring (stiffness 60, damping 20, mass 0.8) for springProgress (0→1), useTransform to derive clipPercentage (0→100), progressBarScale (0→1), and a live progressPct text. Auto-animate slider to 1 on isInView (useInView margin '-80px') with 400ms delay via useEffect, gated by hasInteracted ref. Support manual drag via handlePointerDown/handlePointerMove/handlePointerUp updating springProgress from pointer position relative to sliderRef. Render pdfLines array (10 items with width % and type 'data'|'highlight') as animated scan lines, tableRows (6 commission records with client/carrier/amount/status) as a parsed result table, and 3 benefits cards (speed ⚡, accuracy ◎, auto ⟳) with iconClass variants.
Implement UserPersonas for Landing
As a frontend developer, implement the UserPersonas section with 3 persona accordion cards (Admin/Shield, Agent/Users, Financial Analyst/BarChart3 from lucide-react). Each persona has an id, name, role, icon, description, responsibilities array, and flowHref. Expand/collapse is driven by activeId state; clicking a persona sets activeId or toggles off. AnimatePresence wraps the body with bodyVariants (height 0→auto, opacity 0→1, staggered exit). Responsibilities list uses listVariants (staggerChildren 0.1, delayChildren 0.15) with bulletVariants (opacity 0→1, x -20→0). Description uses descVariants (y 8→0). Each expanded card shows a 'View Flow →' link with linkVariants. ChevronDown icon rotates 0→180deg on expand.
Implement TechStack for Landing
As a frontend developer, implement the TechStack section displaying 5 technology cards (React 18+, Vite, Tailwind CSS, Firebase, Google GenAI). Each card contains an inline SVG logo (custom paths/ellipses/circles with brand colors: #61DAFB, #BD34FE, #38BDF8, #FFC400, #1A3D6C), a tech name, slug, color accent, and desc string. Use framer-motion for staggered card reveal on scroll into view. The Vite card SVG uses a linearGradient (id 'viteGrad') from #41D1FF to #BD34FE. Cards should apply hover lift effect. Layout is a responsive grid collapsing from 5-col to 2-col on mobile.
Implement Testimonials for Landing
As a frontend developer, implement the Testimonials section with a 3-card auto-advancing carousel (AUTO_INTERVAL 5000ms). State is [[activeIndex, direction], setPage] tracking swipe direction for AnimatePresence cardVariants (enter: x ±120 + opacity 0 + scale 0.95, center: spring stiffness 300 damping 30, exit: reverse). Progress bar advances via requestAnimationFrame in progressRef tracking elapsed time. paginate() and goTo() callbacks reset progress to 0. Touch/drag support via dragStartX ref and SWIPE_THRESHOLD 50px. Each testimonial shows quote, name, title, company, initials avatar, and star rating (5 stars). clearInterval on unmount via intervalRef.
Implement LandingCTA for Landing
As a frontend developer, implement the LandingCTA section with a confetti burst and demo confirmation interaction. generateParticles(14) creates particles with angle/distance/color/size/rotation using CONFETTI_COLORS array (#F2C94C, #1A3D6C, #D94E1F, #3F6BAA, #F2994A, #ffffff). handleGetStartedClick fires particles (cleared after 900ms via setTimeout) via primaryRef. handleScheduleDemoClick toggles showConfirm state (auto-clears after 1800ms via confirmTimeoutRef). Background has 3-layer parallax: lc-parallax-bg (--scroll * -0.25px) with lc-orb divs, lc-parallax-mid (--scroll * -0.45px) with lc-diamond divs. CTA card uses whileInView (opacity 0→1, y 40→0) with staggered headline and subheadline animations.
Implement Footer for Landing
As a frontend developer, implement the Footer shared component (sections/Footer.jsx) reused across pages. Build a motion.footer with ftr-parallax-bg layer (--scroll * -0.15px) containing 3 ftr-bg-orb decorative divs. Top area: brand logo ('winter-commission' with ftr-logo-accent span), tagline, and social icons row (FaLinkedinIn, FaTwitter, FaGithub, FaYoutube from react-icons/fa) with socialVariants (opacity 0 + scale 0.6 → 1). Link columns use containerVariants (staggerChildren 0.12, delayChildren 0.1) with columnVariants (opacity 0→1, y 30→0) for 4 columns: Product (5 links), Company (4 links), Resources (5 links), Legal (4 links). Bottom bar shows copyright text.
Define Firestore Data Models
Create typed TypeScript/JS data models and Firestore service layer for all collections: clients (name, department, active, firstCommissionDate), agents (name, title, email, splitPercentage, totalEarned), policies (policyNumber, carrierName, coverageType, clientId, clientName, status), policies/{policyId}/splits sub-collection (agentId, percentage), and commission_entries (amount, payDate, serviceMonth, carrierId, clientId, policyId, agentId, department). Include CRUD helper functions for each collection. Note: all page sections reading/writing data depend on this.
Set Up Global State Management
Implement global application state using React Context + useReducer (or Zustand if complexity warrants): (1) AuthContext for Firebase Auth user session, (2) SelectedChildContext / AppContext holding currently active agent/client selection for sidebar focus-mode panels, (3) UploadContext holding parsed statement data flowing from Upload → ConflictResolution → commit, (4) NotificationContext for toast/alert system across all pages. Export typed hooks (useAuth, useAppState, useUpload, useNotification) for clean consumption in all page sections.
Seed Firestore Sample Data
Create a seed script to populate Firestore with realistic sample data: 5–10 clients (mix of Group/Individual departments), 3–5 agents with split percentages, 10–15 policies with splits sub-collection entries, and 30–50 commission_entries spanning at least 12 months for meaningful report filtering and chart visualization. Script should be idempotent and runnable via npm script.
Build Gemini AI Parse Service
Implement a Google GenAI (Gemini 1.5 Pro/Flash) service layer that accepts uploaded file content (Excel/CSV parsed to JSON, or PDF text extracted via pdf-parse or similar) and returns structured commission data: client name, carrier, coverage type, amount, pay date, service month, policy/group number, agent name, and participation percentage. Include prompt engineering for robust extraction, confidence scoring per field, and error handling for ambiguous/missing fields. Auto-classify Medicare entries to 'Individual' department. This service is consumed by the Upload page AI parsing flow and ConflictResolution page. Note: depends on firebase models for client auto-mapping lookup.
Implement Commission Entry Write Service
Create a Firestore write service that handles the final commit of parsed and conflict-resolved commission data: (1) upsert client records (create if new, update department if changed per sync logic), (2) upsert policy records with splits sub-collection, (3) upsert agent records updating totalEarned, (4) batch-write commission_entries. Implement the department sync logic: prompt or auto-update when a Group client has a Medicare entry. Handle Firestore batch write limits (max 500 ops per batch). This service is called from the ConflictResolution confirm step. Note: ConflictResolution and Upload page sections depend on this.
Build Financial Reporting Query Service
Implement a Firestore query and aggregation service for the Reports page: (1) multi-level grouping by Agent, Department, Client, Carrier, or Policy from commission_entries, (2) time-based filtering by custom date range, YTD, or Last Year using payDate field, (3) compute Revenue (Gross = sum of amount) and Yield (Net = amount * splitPercentage) per group, (4) CSV export function using papaparse or manual CSV string generation for filtered results. Return structured aggregation objects suitable for Recharts rendering. Note: Reports page sections depend on this.
Build Dashboard Stats Query Service
Implement Firestore query functions for the Dashboard page overview: total revenue YTD, total yield YTD, active client count, active agent count, recent commission entries (last 10), upcoming/recent upload activity, and per-agent yield summary for the current user. Also compute trend data (monthly revenue/yield for last 12 months) for Recharts chart rendering. Note: Dashboard page sections depend on this; link to tmp_firestore_models.
Implement Salesforce Periodic Sync
Build a Salesforce integration service for periodic commission record attachment: (1) OAuth2 connected app authentication using jsforce or Salesforce REST API, (2) a sync function that queries Firestore commission_entries updated since lastSyncAt timestamp and upserts matching Salesforce records (Opportunity or custom object) by clientId/policyId, (3) store lastSyncAt in a Firestore 'settings' document after each run, (4) expose a manual 'Sync Now' trigger callable from the Settings page. Schedule can be simulated via Settings UI trigger (no server-side cron needed for single-user utility). Note: Settings page Salesforce sync section depends on this.
Configure React Router & Auth Guards
Set up React Router v6 with routes for all 11 pages: / (Landing), /login (Login), /dashboard (Dashboard), /upload (Upload), /conflict-resolution (ConflictResolution), /clients (Clients), /agents (Agents), /settings (Settings), /policies (Policies), /profile (Profile), /reports (Reports). Implement a ProtectedRoute wrapper that checks Firebase Auth state (from AuthContext) and redirects to /login if unauthenticated. Add a PublicRoute guard redirecting authenticated users away from /login and /. Configure lazy loading (React.lazy + Suspense) for all internal pages to optimize initial bundle size.
Build Shared Sidebar Navigation
Implement a shared Sidebar component (sections/Sidebar.jsx or components/Sidebar.jsx) used across all internal pages (Dashboard, Upload, ConflictResolution, Clients, Agents, Settings, Policies, Profile, Reports). Include nav items with Lucide icons: Dashboard (LayoutDashboard), Upload (Upload), Clients (Users), Agents (Briefcase), Policies (FileText), Reports (BarChart3), Settings (Settings), Profile (User). Active route highlighted using primary_light. Collapsible to icon-only mode on desktop, full-height drawer on mobile with framer-motion AnimatePresence. Show user display name and logout button at bottom.
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!