ShoeBox CRM - Technical Description for Patent Application

Hierarchical Data Isolation with Branding Inheritance

The system implements a unique three-tier isolation model where each record contains both an organization_id (brokerage) and derives agency context from the organization. Branding cascades from agency → organization → user, with each level able to override inherited values. The client portal resolves branding by checking user-level customizations first, then organization branding, then agency branding, ensuring consistent white-label presentation.

Automated Property Valuation with Equity Alerts

The system periodically fetches updated property valuations from Attom Data API and stores them with timestamps. It calculates equity by subtracting current loan balance from estimated value, compares to previous equity calculations, and generates notifications when equity increases by a threshold percentage (e.g., 10%). The system maintains mortgage amortization schedules based on original loan terms to project future equity positions.

Dynamic Client Portal with Transaction Context

Unlike traditional agent-side interfaces, the client portal is a separate authenticated view that displays only transaction-specific information. When a client logs in, the system queries all transactions where they are linked as a contact, retrieves associated documents and checklist items, and presents them in a branded interface matching their agent's settings. Clients can upload documents, complete e-signatures, view transaction timelines, and message their agent—all without accessing the broader CRM data.

Intelligent Automation with Conditional Execution

The automation engine evaluates rules on a scheduled basis (e.g., every 5 minutes) by querying for recent entity changes. Each rule defines a trigger entity, field conditions (status=X, date<Y), and actions (send email, create task, enroll in drip campaign). The system maintains execution history to prevent duplicate actions and supports conditional branching in drip campaigns based on recipient behavior (email opened, link clicked).

Gamification with Dual-Context (Agent & Client)

The gamification engine tracks points in separate contexts—agent-side for CRM activities and client-side for portal engagement. Points are awarded asynchronously after actions complete, with configurable values per action type. The system maintains daily login streaks with "freeze" days that prevent streak breaks, unlocks achievements when criteria are met, and generates comparative leaderboards. Team competitions track aggregate points across designated team members with real-time ranking.

MLS Integration with Bulk Import and Monitoring

The system authenticates with MLS providers (e.g., MetroMLS via ScrapingBee API) and implements property search with criteria filtering. Search results can be bulk-imported, creating property records with full details including photos, property characteristics, and pricing history. The system links properties to customer interest records, enabling agents to track which clients viewed which properties and triggering automated follow-up workflows.

Commission Cap Management

The system tracks accumulated gross commissions against agent-specific cap amounts (e.g., $50,000 annually). When commissions approach the cap threshold, the system sends alerts and adjusts future commission calculations to reflect post-cap split percentages. Cap payments can be recorded in advance, reducing the remaining cap balance. The system supports multiple cap periods (e.g., anniversary-based caps) with automatic rollover.

Transaction Deadline Calculator

Based on the contract acceptance date, the system automatically calculates contingency deadlines using state-specific rules. For example, an inspection contingency might be "10 days from acceptance" while a financing contingency is "30 days from acceptance." These calculated dates populate checklist items and trigger reminder notifications at configurable intervals (e.g., 3 days before, 1 day before, day of).

Activity Verification Workflow

For organizations requiring proof of activities (to prevent gaming of the gamification system), agents can upload proof documents (receipts, photos) when logging activities. These enter a verification queue visible to admins, who can approve or reject with reasons. Points are only awarded after admin approval. The system supports configurable verification requirements per activity type.

Unified Communication Timeline

All communications (emails, SMS, calls) are displayed in a chronological timeline view for each customer. The system automatically links inbound communications by matching phone numbers or email addresses to customer records. Email OAuth integrations enable two-way sync with Gmail/Outlook, displaying both sent and received messages. SMS integration via Twilio provides threaded conversations with delivery status tracking.

Authentication & Authorization

The system uses JWT-based authentication with role-based access control (RBAC). Users authenticate via email/password or OAuth (Google, Microsoft). Each request includes the user's organization context, which filters database queries through row-level security policies. The permission system supports granular controls (e.g., "can view team analytics" vs "can only view own data").

Real-Time Updates

The frontend uses React Query with polling intervals to fetch fresh data. Critical updates (new messages, signature completions) trigger WebSocket events that immediately update the UI. The system implements optimistic updates for user actions, providing instant feedback before server confirmation.

Document Storage & Security

Documents are stored in cloud object storage with private access controls. When a user requests a document, the system generates a time-limited signed URL (e.g., valid for 5 minutes) that provides temporary direct access. Document access is logged for audit trails. The system supports automatic virus scanning on upload.

API Integration Architecture

External API integrations are implemented as serverless functions (Deno) that authenticate using environment secrets. OAuth tokens are stored encrypted and refreshed automatically before expiration. Webhook receivers validate signatures from external services (DocuSign, Twilio) before processing events. Rate limiting protects against API quota exhaustion.

Search & Filtering

The global search feature queries across multiple entity types (customers, properties, transactions) using fuzzy matching on key fields. Results are ranked by relevance and recency. The system implements debounced search to reduce server load, waiting for typing pauses before executing queries. Advanced filters support complex criteria combinations (e.g., "buyers with budget > $500k in ZIP codes 12345, 12346").

Performance Optimization

The system employs query result caching with 5-minute TTLs for frequently accessed data (user profile, organization settings). Database queries use indexed lookups on owner and organization_id fields. The frontend implements code splitting to load only necessary components, reducing initial load time. Background tasks (MLS sync, automation processing) run on scheduled intervals to avoid blocking user requests.

Method for Dynamically Resolving Branding in a Hierarchical Multi-Tenant System

1. Receive a request from a user authenticated in the system
2. Identify the user's organizational context (agency_id, organization_id, user_id)
3. Query branding configuration at user level for specified attributes (logo, colors, display name)
4. For each missing attribute, query organization level configuration
5. For each still-missing attribute, query agency level configuration
6. For each still-missing attribute, apply system default values
7. Return resolved branding object with complete attribute set
8. Cache resolved branding with TTL for subsequent requests

Method for Automated Equity-Based Client Re-Engagement

1. On scheduled interval, query all properties with equity_alert_enabled=true
2. For each property, fetch current valuation from one or more external data sources
3. Store new valuation with timestamp (api_estimated_value, api_last_updated)
4. Calculate current equity: estimated_value - current_loan_balance
5. Retrieve previous equity calculation from property history
6. Calculate equity growth percentage: (current_equity - previous_equity) / previous_equity * 100
7. If growth exceeds threshold (e.g., 10%) and sufficient time has passed since last alert (e.g., 90 days)
8. Identify customer records linked to property via ownership or past transactions
9. Generate notification record for agent with equity growth details
10. Optionally trigger automated email/SMS to customer with personalized equity update
11. Update last_equity_alert date on property record
12. Log equity tracking event for analytics

Method for Conditional Automation Execution with Duplicate Prevention

1. On scheduled interval (e.g., every 5 minutes), retrieve all active automation rules
2. For each rule, query target entity type for records updated since last execution
3. Filter records matching trigger conditions (field comparisons, date ranges, status values)
4. For each matching record, generate unique execution key: hash(rule_id, record_id, record_updated_date)
5. Query execution history table for existence of execution key
6. If execution key exists, skip (prevents duplicate actions)
7. If execution key does not exist, execute defined actions sequentially
8. For email action: resolve template, merge record data, send via configured provider
9. For task action: create notification record linked to agent and entity
10. For drip enrollment action: create enrollment record with current step=0
11. For field update action: modify target record with specified values
12. After successful execution, insert execution key into history with timestamp
13. Log automation execution result (success/failure) for auditing
14. Continue to next matching record

Method for Transaction Deadline Calculation with State-Specific Rules

1. Upon creation of transaction record, retrieve contract_date (acceptance date)
2. Identify transaction's property location (state, county)
3. Load applicable checklist template based on transaction_type and location
4. For each checklist item with relative deadline (e.g., "10 days from acceptance")
5. Parse deadline formula to extract offset value and unit (days/weeks)
6. Calculate absolute deadline date: contract_date + offset
7. Adjust for business days if specified (skip weekends/holidays)
8. Create checklist item record with calculated due_date
9. Schedule reminder notifications at intervals (e.g., 3 days before, 1 day before, day of)
10. If contract_date changes, recalculate all relative deadlines and update records
11. Display calculated deadlines in transaction timeline view

Method for White-Label Client Portal Authentication and Data Filtering

1. Client accesses portal URL and initiates authentication
2. System verifies client credentials and loads associated customer record
3. Query all transaction_contact records where customer_id matches authenticated client
4. Extract unique transaction_ids from contact records
5. For each transaction, load transaction details, associated property, and agent information
6. Resolve branding configuration from agent's organizational hierarchy
7. Apply resolved branding to portal interface (logo, colors, display name)
8. Query documents where related_entity_id in transaction_ids
9. Query checklist items where transaction_id in transaction_ids
10. Query e-signature requests where transaction_id in transaction_ids and customer is a signer
11. Filter all data to exclude records client should not access
12. Render portal interface showing only transaction-specific information
13. Establish WebSocket connection for real-time updates within client's transaction scope

Method for Commission Cap Tracking with Automatic Split Adjustment

1. Agent defines annual cap amount and cap period (e.g., $50,000 per anniversary year)
2. Upon creation of commission record, calculate gross_commission from sale_price * commission_rate
3. Apply brokerage_split percentage to determine brokerage portion
4. Apply franchise_fee_rate to gross_commission to calculate franchise_fee
5. Calculate net_commission: gross_commission - (brokerage portion) - franchise_fee
6. Query sum of all gross_commissions for agent within current cap period
7. Compare accumulated commissions to cap amount
8. If accumulated < cap, apply pre-cap split percentages
9. If accumulated >= cap, apply post-cap split percentages (typically 100% to agent)
10. If transaction crosses cap threshold (before < cap, after >= cap), split calculation proportionally
11. Generate notification when accumulated commissions reach 80% of cap
12. Generate notification when cap is reached
13. Update running cap balance in agent profile
14. Display cap progress in agent dashboard with visual indicator

Method for Gamification Point Award with Achievement Unlocking

1. User completes an action (logs activity, closes deal, etc.)
2. System identifies action type and context (agent vs client)
3. Query point configuration for action type to determine point value
4. Create GamificationPoints record with user, action type, points, and timestamp
5. Update user's total point balance
6. Query all achievements to identify those with unmet criteria
7. For each achievement, evaluate criteria against user's history (total points, activity counts, streak days)
8. If criteria newly satisfied, create UserAchievement record with unlock timestamp
9. Award bonus points for achievement unlock if configured
10. Trigger notification to user with achievement details and celebration animation
11. Update leaderboard rankings across all timeframes (daily, weekly, monthly, all-time)
12. If user is in team competition, add points to team aggregate score
13. Update team competition rankings
14. Check for login streak continuation and apply freeze day if needed

Organizational Hierarchy Variations

• Two-tier structure (brokerage → agent) without agency level
• Four-tier structure (corporation → region → brokerage → agent)
• Flat structure with single organization containing multiple agents
• Matrix structure where agents belong to multiple teams simultaneously
• Franchise model with national brand → franchisee → office → agent hierarchy

Property Valuation Sources

• Multiple external valuation APIs (Attom, Zillow, Redfin, CoreLogic, Black Knight)
• MLS comparable sales analysis algorithms
• Manual agent-entered valuations with override capability
• AI/ML models trained on local market data
• Automated Valuation Models (AVMs) from lenders
• Weighted average of multiple sources with confidence scoring
• Real-time bid/ask data from property marketplaces

Automation Trigger Mechanisms

• Scheduled polling at configurable intervals (1 min, 5 min, 15 min, hourly)
• Event-driven triggers via database webhooks/listeners
• Real-time stream processing of entity change logs
• Batch processing during off-peak hours
• On-demand execution via manual trigger buttons
• Conditional chaining where one automation triggers another

Communication Channel Alternatives

• Email via multiple providers (SendGrid, Mailgun, AWS SES, Gmail API, Outlook API)
• SMS via multiple gateways (Twilio, Plivo, MessageBird, Bandwidth)
• Voice calls via VoIP providers (Twilio, RingCentral, 8x8)
• In-app messaging with WebSocket/long-polling
• WhatsApp Business API integration
• Facebook Messenger integration
• Push notifications to mobile apps

E-Signature Integration Options

• Third-party services (DocuSign, Adobe Sign, HelloSign, PandaDoc)
• Native e-signature implementation with certificate authorities
• Blockchain-based signature verification
• Biometric signature capture on mobile devices
• Video-based signature verification
• Government-approved digital identity providers

Gamification Scoring Models

• Fixed points per action type
• Variable points based on deal value or complexity
• Time-decay scoring (recent actions worth more)
• Multiplier bonuses for consecutive days or rapid completion
• Negative points for missed deadlines or expired leads
• Peer comparison scoring relative to team average
• Weighted scoring emphasizing strategic priorities

MLS Integration Approaches

• Direct API integration with MLS providers (RETS, Web API)
• Screen scraping with automation tools (Selenium, Puppeteer, ScrapingBee)
• IDX feed parsing and ingestion
• Third-party aggregation services (Bridge Interactive, FBS)
• Real estate data platforms (Zillow API, Realtor.com API)
• Manual CSV import with field mapping

Database and Storage Architectures

• Relational databases (PostgreSQL, MySQL, SQL Server)
• NoSQL databases (MongoDB, DynamoDB, Firestore)
• Hybrid SQL + document storage for custom fields
• Graph databases for relationship-heavy queries (Neo4j)
• Cloud object storage (AWS S3, Google Cloud Storage, Azure Blob)
• Content delivery networks for media assets
• Multi-region replication for global availability

Client Portal Authentication Methods

• Email/password with secure password reset
• Magic link authentication (passwordless email links)
• SMS-based one-time passwords
• Social login (Google, Facebook, Apple)
• Biometric authentication (fingerprint, face recognition)
• Two-factor authentication with TOTP apps
• Single sign-on (SSO) via SAML/OAuth

External Data Integration Layer

The system interfaces with one or more external property data sources to obtain valuations, market statistics, property characteristics, and ownership records. These sources may include proprietary databases, public records aggregators, real estate marketplaces, or governmental databases. The integration layer standardizes data formats and provides fallback mechanisms when primary sources are unavailable.

Communication Delivery Infrastructure

The system employs one or more message delivery services to transmit communications (email, SMS, voice) to clients and agents. These services provide delivery confirmation, bounce handling, and compliance with anti-spam regulations. The system abstracts provider-specific APIs through a unified interface, enabling seamless provider switching or multi-provider redundancy.

Document Signature Workflow Engine

The system integrates with one or more electronic signature services to facilitate legally binding document execution. The workflow engine manages signer sequencing, field placement, reminder scheduling, and completion tracking. Integration may occur via REST APIs, webhooks, or embedded SDKs, with signature validity verified through cryptographic certificates or third-party attestation services.

Real Estate Listing Data Synchronization

The system connects to one or more multiple listing services (MLS) or property listing aggregators to retrieve current market inventory. Synchronization may occur through standardized protocols (RETS, RESO Web API), proprietary APIs, data feeds (IDX), or automated data extraction techniques. The system normalizes listing data across sources and maintains local copies with periodic refresh to reflect market changes.

Configurable Workflow Automation System

The system provides a rules engine where users define trigger conditions (entity state, field values, time thresholds) and corresponding actions (notifications, data updates, external API calls). Rules are evaluated on a scheduled basis or in response to events, with execution history maintained to prevent duplicate processing. The engine supports conditional logic, variable substitution, and sequential action chains.

User Engagement and Gamification Framework

The system implements a configurable points-and-rewards mechanism that tracks user activities, assigns point values, unlocks achievements based on criteria, and generates comparative rankings. The framework supports multiple contexts (agent productivity vs client engagement), time-bound challenges, team aggregations, and persistent streak tracking. Point values and achievement definitions are administrator-configurable to align with organizational goals.