Marketplace System — Clustering, Contribution, Network Effects

Overview

The marketplace enables precedent discovery and sharing through intelligent clustering. Precedents are grouped by (payer, denial_type, LOC), creating clusters of related cases. Clusters gain value as multiple tenants contribute — creating a network effect that incentivizes contribution and gates access.

Core Design Principles

Deterministic Clustering —

cluster_id = "Payer  LOC" is deterministic and immutableNetwork Effect Gate — Clusters appear in marketplace only after 2+ distinct tenants contribute (MIN_CLUSTERS_FOR_MARKETPLACE = 2)
Contribution-Based Access — Tenants earn credits for contributions, spend credits to query clusters
Maturity Tiers — Clusters progress through tiers (Embryonic → Emerging → Mature → Canonical) as they grow
Aggregate Intelligence — Cluster-level metrics synthesize evidence, outcomes, and patterns from all members
Clustering Algorithm
Cluster ID Generation

For any precedent, cluster_id is deterministic:

def cluster_id(payer: str, denial_type: str, loc: Optional[str]) -> str:
    """Generate cluster_id from precedent fields.
    
    Args:
        payer: Insurance company name (e.g., "Cigna")
        denial_type: Denial category (e.g., "Frequency Limit")
        loc: Level of care or None for non-LOC denials
    
    Returns:
        Cluster ID in format "Payer 
"
    """
    if loc is None:
        return f"{payer} "
    return f"{payer}  {loc}"Examples:Cigna IOP frequency limit: "Cigna 
 IOP"UHC medical necessity (any LOC): "UHC 
"Aetna PHP-only: "Aetna 
 PHP"

Cluster Discovery

When precedent is created:

-- Step 1: Calculate cluster_id
cluster_id = cluster_id(precedent.payer, precedent.denial_type, precedent.loc)

-- Step 2: Check if cluster exists
SELECT id FROM marketplace_clusters WHERE cluster_id = ?

-- Step 3: If not, create it
INSERT INTO marketplace_clusters (cluster_id, payer, denial_type, loc, contributor_count, ipo_count)
VALUES (?, payer, denial_type, loc, 1, 1);

-- Step 4: Increment ipo_count if cluster exists
UPDATE marketplace_clusters SET ipo_count = ipo_count + 1 WHERE cluster_id = ?

-- Step 5: Check if contributor is already in cluster
SELECT COUNT() FROM contribution_scores 
WHERE cluster_id = ? AND tenant_id = current_tenant_id

-- Step 6: If new contributor, increment contributor_count
UPDATE marketplace_clusters SET contributor_count = contributor_count + 1 WHERE cluster_id = ?
INSERT INTO contribution_scores (tenant_id, cluster_id, ipo_count) VALUES (?, ?, 1)
Network Effect Gate
KEY RULE: Clusters only appear in marketplace after 2+ distinct tenants contribute.

Why? Prevent single-tenant seed data from polluting marketplace. Force genuine multi-tenant collaboration.

Implementation:-- Query for browsable clusters (marketplace)
SELECT  FROM marketplace_clusters
WHERE tenant_id = $1  -- Current tenant
  AND contributor_count >= 2  -- Network gate
  AND maturity_tier IN ('Emerging', 'Mature', 'Canonical')
ORDER BY ipo_count DESC;

-- Query for my clusters (showing progression toward marketplace)
SELECT  FROM marketplace_clusters
WHERE tenant_id = $1
ORDER BY contributor_count DESC, ipo_count DESC;
Lifecycle Example:Maturity Tiers

Clusters progress through maturity based on growth metrics:

Embryonic (Tier 1)
Criteria: 1 contributor, any precedent count
State: Private, not in marketplace
Signals: Single tenant exploring domain
Actions: Owner can refine, validate, prepare for sharing
Emerging (Tier 2)
Criteria: 2–3 contributors, <10 precedents
State: Public (appears in marketplace)
Signals: Early multi-tenant collaboration
Incentive: First contributor bonus (extra credits) for unlocking marketplace
Actions: Community building, evidence synthesis
Mature (Tier 3)
Criteria: 4+ contributors, 10+ precedents, 50%+ win rate
State: Public, featured
Signals: Proven evidence base, consistent outcomes
Incentive: Higher-quality precedents earn more credits
Actions: Drift monitoring, narrative pattern synthesis
Canonical (Tier 4)
Criteria: 20+ precedents, 70%+ win rate, <7 days avg resolution
State: Public, pinned, featured
Signals: Gold standard for denial pattern
Incentive: Highest credit rewards, referenced in training
Actions: Annual validation, evidence synthesis
Tier Progression

Recalculate nightly or on precedent creation:

UPDATE marketplace_clusters
SET maturity_tier = CASE
  WHEN contributor_count = 1 THEN 'Embryonic'
  WHEN contributor_count <= 3 AND ipo_count < 10 THEN 'Emerging'
  WHEN contributor_count >= 4 
    AND ipo_count >= 10 
    AND (SELECT COUNT() FILTER(WHERE outcome='Won') FROM precedent_objects WHERE cluster_id = mc.cluster_id) / ipo_count > 0.5
  THEN 'Mature'
  WHEN ipo_count >= 20 
    AND (SELECT COUNT() FILTER(WHERE outcome='Won') FROM precedent_objects WHERE cluster_id = mc.cluster_id) / ipo_count > 0.7
    AND (SELECT AVG(time_to_resolution_days) FROM precedent_objects WHERE cluster_id = mc.cluster_id) < 7
  THEN 'Canonical'
  ELSE 'Emerging'
END
WHERE last_refreshed < NOW() - INTERVAL '1 day';
Aggregate Metrics

Each cluster synthesizes data from all member precedents:

win_rate
SELECT COUNT() FILTER(WHERE outcome='Won')  100.0 / COUNT() AS win_rate
FROM precedent_objects
WHERE cluster_id = $1;
Use: Indicate cluster strength. "70%+ win rate = Canonical"

avg_resolution_days
SELECT AVG(time_to_resolution_days) AS avg_resolution
FROM precedent_objects
WHERE cluster_id = $1 AND outcome IN ('Won', 'Lost', 'Partial');

Use: Indicate efficiency. "<7 days = gold standard"

top_evidence_types
{
  "clinical_notes": 0.85,  // 85% of successful appeals used clinical notes
  "psychiatric_evaluation": 0.78,
  "gaf_score": 0.92,
  "functional_assessment": 0.45
}

Use: Guide new contributors on what evidence to gather.

narrative_patterns
{
  "functional_impact": 0.85,      // 85% of Won appeals emphasized functional impact
  "evidence_combination": 0.72,
  "escalation_path": 0.40,
  "parity_law_reference": 0.55
}

Use: Show what narrative strategies work for this denial type.

evidence_kit_composite

Merged evidence requirements from all cluster precedents:

{
  "required": [
    "Clinical notes (30 days)",
    "Psychiatric evaluation",
    "GAF score",
    "Functional assessment"
  ],
  "recommended": [
    "Prior hospitalization records",
    "School/work functional history"
  ],
  "optional": [
    "Research articles",
    "Expert opinions"
  ]
}

Use: New users building appeal in this cluster know exactly what evidence to gather.

Drift Detection

Clusters are flagged if metrics trend negatively:

{
  "outcome_trending_down": false,           // Win rate declining month/month
  "resolution_time_increasing": false,      // Taking longer to resolve
  "contributor_churn": false,               // Contributors leaving (count decreasing)
  "evidence_effectiveness_declining": false // New precedents have lower win rate
}

Trigger: Recalculated on precedent update or nightly

Example:
-- Check if win_rate is declining
SELECT 
  DATE_TRUNC('month', created_at)::DATE AS month,
  COUNT() FILTER(WHERE outcome='Won')  100.0 / COUNT() AS win_rate
FROM precedent_objects
WHERE cluster_id = $1 AND created_at > NOW() - INTERVAL '12 months'
GROUP BY DATE_TRUNC('month', created_at)
ORDER BY month DESC;
Action: If trending down > 10% MoM, flag cluster for review.

Credit Integration
Contribution Mint (Create Precedent)

When precedent is added to cluster:

-- Calculate credits earned
credits = base_amount  evidence_quality_multiplier
base_amount = 10
multiplier = 1.0 (Minimal) 
Denial Type







Denial Type LOC" or "Payer Denial Type
 {denial_type}
 {denial_type}


Frequency Limit
Medical Necessity 
Level of Care









Event Cluster State Visible?

Tenant A creates first precedent contributor_count=1 (Embryonic) Private (A only)
Tenant B creates second precedent contributor_count=2 (Emerging) Public (appears in marketplace)
Tenant C creates third contributor_count=3 (Mature) Public
10 more from mixed tenants contributor_count=13 (Canonical) Public (top tier)





































1.5 (Moderate)
 2.0 (Strong)

-- Log to credit_ledger
INSERT INTO credit_ledger (
  event_type='contribution_mint',
  amount=credits,
  tenant_id=current_tenant,
  reference_id=precedent_id,
  metadata={'evidence_score': '...', 'outcome': '...'}
);

-- Update contribution_scores
UPDATE contribution_scores 
SET ipo_count = ipo_count + 1
WHERE tenant_id = current_tenant AND cluster_id = ?;

Query Burn (Access Cluster)

When tenant queries cluster:

-- Calculate query cost
cost = 1 + (ipo_count / 10  0.5)
-- 10-precedent cluster = 1.5 credits
-- 50-precedent cluster = 3.5 credits

-- Check balance
IF balance < cost THEN
  RETURN 402 Payment Required

-- Burn credits
INSERT INTO credit_ledger (
  event_type='query_burn',
  amount=-cost,
  reference_id=cluster_id,
  metadata={'ipo_count': ...}
);

-- Return cluster data

Marketplace API Flows

Browse Clusters

GET /api/marketplace/clusters?payer=Cigna&loc=IOP
→ List clusters where contributor_count >= 2
→ Show: cluster_id, ipo_count, win_rate, maturity_tier
→ Cost: 0 credits (browsing free)

View Cluster Profile

GET /api/marketplace/clusters/{cluster_id}
→ Check balance >= query cost
→ Burn credits from ledger
→ Return: full cluster stats, top evidence types, narrative patterns, composite evidence kit
→ Cost: 1 + (ipo_count / 10 * 0.5) credits

List My Contributions (Contribution History)

GET /api/marketplace/contributions?tenant_id=current
→ List clusters where I contributed >= 1 precedent
→ Show: cluster_id, my_ipo_count, gap_score, total_score, tier, status
→ Cost: 0 credits

Compliance Notes

SUD Data in Clusters:

If cluster contains SUD precedents, mark has_sud_content = true


SUD clusters subject to special sharing rules (42 CFR Part 2)
Mark cluster in UI: "⚠️ Contains SUD data — sharing restricted"

HIPAA Audit:
Every cluster query logged to marketplace_queries table
Query access is compliance event (logged to precedent_audit_log)

See also
Marketplace Tables — marketplace_clusters schema
Credit Economy — Mint/burn rules and incentive design
Data Models Overview — Cluster relationships

Code reference
src/services/marketplace.ts — Clustering logic, tier calculation, drift detection
src/routes/marketplace.ts — API endpoints (browse, profile, query)
src/models/marketplace.ts — Query helpers (lookup, metrics, scoring)
src/db/marketplace-schema.sql — marketplace_clusters definition

Marketplace System — Clustering, Contribution, Network Effects

Marketplace System — Clustering, Contribution, Network Effects

Overview

Core Design Principles

Clustering Algorithm

Cluster ID Generation

Cluster Discovery

Network Effect Gate

Maturity Tiers

Embryonic (Tier 1)

Emerging (Tier 2)

Mature (Tier 3)

Canonical (Tier 4)

Tier Progression

Aggregate Metrics

`win_rate`

`avg_resolution_days`

`top_evidence_types`

`narrative_patterns`

`evidence_kit_composite`

Drift Detection

Credit Integration

Contribution Mint (Create Precedent)

Query Burn (Access Cluster)

Marketplace API Flows

Browse Clusters

View Cluster Profile

List My Contributions (Contribution History)

Compliance Notes

See also

Code reference

Denial Type
Denial Type	LOC" or "Payer	Denial Type
{denial_type}
{denial_type}
Frequency Limit
Medical Necessity
Level of Care
Event	Cluster State	Visible?
Tenant A creates first precedent	contributor_count=1 (Embryonic)	Private (A only)
Tenant B creates second precedent	contributor_count=2 (Emerging)	Public (appears in marketplace)
Tenant C creates third	contributor_count=3 (Mature)	Public
10 more from mixed tenants	contributor_count=13 (Canonical)	Public (top tier)
1.5 (Moderate)