Technical Documentation

Implementation Questions

Questions, clarifications, and schema design decisions for the HURE Map Integration project.

Last updated: December 19, 2025

Confirmed Business Requirements

County Coverage
Many-to-many Multiple brokerages can share a county
Lead Distribution
TBD Open question (see Q11 below)
Map Display
Featured broker + see more Highlight top-tier, expandable list
Lead Notification
All Partners Every agent at enrolled brokerages gets notified
Partner Definition Individual agent within a Brokerage
Military Badge Derived from broker military_specialist flag
County Status
Derived Computed from BrokerCounty records

Open Questions

OPEN Stripe / Billing
Q1: Enrollment Tier Pricing
The spec mentions Enrollment tiers but does not specify exact pricing for each tier.

Current assumption:

  • Basic: $299 (one-time)
  • Premium: $499 (one-time)
  • Enterprise: $999 (one-time)

Question: What are the actual one-time enrollment fees for each tier?

OPEN Stripe / Billing
Q2: What differentiates the tiers?
The spec mentions tiers but does not detail feature differences.

Current assumption:

  • Basic: Single county assignment, standard lead routing
  • Premium: Priority placement, enhanced map visibility
  • Enterprise: Multiple counties, premium support

Question: What specific features/benefits does each tier include?

OPEN Stripe / Billing
Q3: Annual Maintenance - When does billing start?
Spec says $100/year maintenance separate from enrollment.

Options:

  1. First maintenance charge 1 year after enrollment
  2. Maintenance charge starts immediately (prorated or full)
  3. Maintenance included in first year, then $100/year renewal

Question: When should the first $100 annual maintenance fee be charged?

OPEN Map / UI
Q5: Multiple Counties per Enterprise Partner?
Enterprise tier mentions multiple counties but implementation currently supports 1:1 county-to-partner.

How should multi-county assignments work?

  • Separate enrollment per county?
  • Bundle pricing for multiple counties?
  • Single subscription covers N counties?

See schema below for support for this. Allowing multiple counties per broker and vice-versa.

OPEN Map / UI
Q6: Military Specialist Badge
Spec mentions Military specialist will later drive a badge/flag on the county map

Questions:

  • What should the badge look like?
  • Where should it appear (popup, map polygon, both)?
  • Is this MVP or post-launch?

Suggestion: Drive off of status(es) of Broker(s) assigned to the County. If one exists with flag, show badge.

OPEN Airtable / Data
Q9: Airtable

What is driving the decision to use Airtable? Are there integrations, other than human accessing the current Airtable data?

OPEN Map / UI
Q10: ESRI Maps

What is driving using ESRI maps? It is really slow, not very customizable. OpenStreetMap would be a good alternative.

OPEN Lead Distribution
Q11: Lead Distribution Algorithm
When multiple brokerages share a county, how should incoming leads be distributed?

Options:

  1. Round-robin: Distribute leads evenly across all brokerages in rotation
  2. Tier-based priority: Premium/Enterprise brokers get leads first, Basic as overflow
  3. Consumer chooses: Show all brokerages, let consumer pick which one to contact
  4. Broadcast: Send to ALL active brokers in the county

Question: Which distribution model fits the business goals best?

Database Schema (Recommended MVP)

Proper schema will prevent lots of pain in the future! This schema supports many-to-many county coverage.

Entity Relationship Diagram

erDiagram
    STATE ||--o{ COUNTY : contains
    COUNTY ||--o{ BROKER_COUNTY : covered_by
    BROKER ||--o{ BROKER_COUNTY : covers
    BROKER ||--o{ PARTNER : employs
    COUNTY ||--o{ LEAD : generates
    LEAD ||--o{ LEAD_ASSIGNMENT : assigned_via
    BROKER ||--o{ LEAD_ASSIGNMENT : receives

    STATE {
        int id PK
        string name
        string abbreviation
    }

    COUNTY {
        int id PK
        string fips UK
        string name
        int state_id FK
        decimal centroid_lat
        decimal centroid_lng
        text area_blurb
        text highlights
        string photo_url
    }

    BROKER {
        int id PK
        string name
        string phone
        string email
        string website
        string logo_url
        string franchise_affiliation
        boolean va_loans
        boolean military_specialist
        string stripe_customer_id
        datetime created_at
    }

    BROKER_COUNTY {
        int id PK
        int broker_id FK
        int county_id FK
        enum tier
        enum status
        string stripe_subscription_id
        date enrollment_date
        date past_due_date
        boolean is_featured
        datetime created_at
    }

    PARTNER {
        int id PK
        int broker_id FK
        string name
        string email
        string phone
        boolean is_lead_recipient
        enum status
        datetime created_at
    }

    LEAD {
        int id PK
        int county_id FK
        string first_name
        string last_name
        string email
        string phone
        string moving_from
        string moving_to
        text message
        string source
        enum status
        datetime created_at
    }

    LEAD_ASSIGNMENT {
        int id PK
        int lead_id FK
        int broker_id FK
        datetime assigned_at
        enum status
        text notes
    }
          

Simplified View

STATE ──1:N── COUNTY ──N:M── BROKER
                 │              │
            (via BROKER_COUNTY) │
                 │              │
                 ▼              ▼
               LEAD         PARTNER
                 │
                 ▼
          LEAD_ASSIGNMENT ◄── tracks which broker(s) got lead
          
BrokerCounty CRITICAL
Many-to-many junction table - enables multiple brokers per county.

Constraint: UNIQUE(broker_id, county_id)

Display Logic:
  • Featured broker: WHERE is_featured = true
  • Tie-breaker: highest tier, then earliest enrollment_date
Field Type Notes
idPK
broker_idFKReferences Broker
county_idFKReferences County
tierenumbasic/premium/enterprise
statusenumactive/past_due/lapsed/canceled
stripe_subscription_idtextStripe subscription reference
enrollment_datedateWhen enrolled
past_due_datedateFor delinquency tracking
is_featuredbooleanShows first in featured broker display
created_atdatetime
Other Core Tables
State, County, Broker, Partner, Lead, LeadAssignment

State

id, name, abbreviation

County

id, fips, name, state_id, centroid_lat/lng, area_blurb, highlights, photo_url

Note: status is DERIVED, not stored

Broker

id, name, phone, email, website, logo_url, franchise_affiliation, va_loans, military_specialist, stripe_customer_id, created_at

Partner

id, broker_id, name, email, phone, is_lead_recipient, status, created_at

Lead

id, county_id, first/last_name, email, phone, moving_from/to, message, source, status, created_at

LeadAssignment

id, lead_id, broker_id, assigned_at, status, notes

Deferred for Future (Not MVP)

GIS subdivision
CountyCentroid No zip-code zone requirement yet
Franchise management
Franchise, FranchiseBroker Text field sufficient for now
Contact normalization
Contact Adds indirection without clear benefit