​

Readiness Data Source Trace — Audit Report

​

1) Route Handlers

​

GET /api/v1/admin/onboarding/businesses/readiness

• File: api/routes/business_onboarding.py
• Handler: get_business_readiness_endpoint() (line 911)
• Query Function: get_business_readiness() (line 932)
• Query File: api/bigquery/business_onboarding_queries.py (line 44)

​

GET /api/v1/admin/onboarding/businesses

• File: api/routes/business_onboarding.py
• Handler: list_businesses_endpoint() (line 77)
• Query Function: list_businesses_for_onboarding() (line 96)
• Query File: api/bigquery/business_onboarding_queries.py (line 285)

​

2) BigQuery Query Functions & Source Tables

​

get_business_readiness() (line 44)

• config_business_onboarding (line 139, 153) — PRIMARY SOURCE
• config_business_policy (line 142) — JOIN for OWNER_ROLLUP policies
• config_business_agent_assignment (line 140) — JOIN for agent assignments
• config_business_agent_pepm_assignment (line 141) — JOIN for PEPM rows

WITH onboarding_businesses AS (
  SELECT DISTINCT co.business_id, co.scope, co.owning_org_id
  FROM config_business_onboarding co
  WHERE co.tenant_id = @tenant_id
    AND co.ignored = FALSE
)
-- LEFT JOINs to assignments, PEPM, policies

​

list_businesses_for_onboarding() (line 285)

• config_business_onboarding (line 424) — PRIMARY SOURCE
• dim_business_mapping (line 423) — JOIN for business identity
• config_business_agent_assignment (line 425) — JOIN for assignments
• config_business_agent_pepm_assignment (line 428) — JOIN for PEPM

WITH business_groups AS (
  SELECT ...
  FROM dim_business_mapping bm
  FULL OUTER JOIN config_business_onboarding co
    ON bm.business_id = co.business_id
  WHERE ...
)

​

3) Discovery Function Analysis

​

Existing Discovery Function

• Manual endpoint: POST /api/v1/admin/onboarding/businesses/refresh-dim (line 881 in routes)
• NOT invoked automatically during:
  • Preflight start
  • Readiness refresh
  • Upload mapping completion

​

Intake Flow Discovery Gap

1. POST /api/v1/intake/upload → Creates batch in ingestion_batches
2. POST /api/v1/intake/{batch_id}/map → Saves column mapping
3. POST /api/v1/intake/{batch_id}/process → Writes to transaction_events_raw (line 473 in intake_processor.py)

• Queries transaction_events_raw for new businesses
• Normalizes business labels
• Upserts into config_business_onboarding

​

4) Confirmation: Discovery NOT Invoked

1. refresh_dim_business_mapping_from_stage1() only upserts to dim_business_mapping, not config_business_onboarding
2. Intake processor (process_batch) writes to transaction_events_raw but does NOT call any discovery function
3. Readiness endpoint queries ONLY config_business_onboarding (does not join with transaction_events_raw or stage1_snapshots)

​

5) P0 Implementation Required

1. Query transaction_events_raw filtered by batch_id (or period_label)
2. Extract DISTINCT business_name_raw values
3. Normalize using normalize_business_name() (matches Python pattern)
4. Generate business_id using generate_business_id() (MD5 hash)
5. Upsert into config_business_onboarding with:
   • first_seen_date = MIN(period_label) from batch
   • last_seen_date = MAX(period_label) from batch
   • instance_count = COUNT(DISTINCT business_name_raw) per normalized group
   • source = ‘INGESTED’
   • scope = NULL (default, can be set later)
   • ignored = FALSE

• After process_batch completes successfully (in intake_processor.py)
• Optional: Manual endpoint for batch-level discovery

• GET /api/v1/admin/onboarding/debug/discover/{batch_id}
• Returns raw labels + normalized labels + business_ids (before upsert)

​

Summary