# Design Decisions — Open Questions

> **CURRENT STATE — 2026-04-21**: none of the 8 decisions below have been made or implemented in code. Document remains an OPEN-QUESTIONS backlog. If a future session implements any of these, update the relevant section with the chosen option + rationale.

## 1. Trigger: When does auto-acquisition fire?

**Option A: Every RFQ**
- Simple, guaranteed coverage
- Risk: wastes API credits on markets we already cover well

**Option B: Threshold-based (recommended)**
- Only fire when qualified vendors for [category + location] < N
- N = configurable per tenant (default: 5? 10?)
- Checks `sm_vendor_leads` where status=qualified AND category_id=X AND state=Y

**Option C: Hybrid**
- Always check threshold
- But also re-acquire if last acquisition for this market was > 30 days ago (stale data)

**Decision needed:** What threshold? What cooldown period?

---

## 2. Market definition: How granular?

When a buyer posts an RFQ for "Plumbing in Atlanta, GA" — what market do we check?

**Option A: Category + State**
- Broader net, fewer acquisitions needed
- Risk: vendors 300 miles away from the buyer

**Option B: Category + State + City (recommended)**
- Matches buyer intent closely
- More acquisitions but more relevant results

**Option C: Category + County**
- Uses existing county demographics data
- Good balance between A and B

**Decision needed:** What geographic scope defines a "market"?

---

## 3. Auto-seed: Should qualified leads become vendors automatically?

Currently seeding is manual (admin clicks "Seed" on platform page).

**Option A: Auto-seed all qualified leads (recommended for this flow)**
- Leads with email + phone + website + address → auto-create vendor + draft listing
- Listing stays draft (not public) until vendor claims and pays
- No admin bottleneck

**Option B: Auto-seed only high-score leads**
- Only seed leads with conversion_score >= 60
- Reduces noise but might miss good vendors

**Option C: Keep manual**
- Defeats the purpose of automation

**Decision needed:** Auto-seed threshold? All qualified? Score-gated?

---

## 4. Email content: What does the vendor see?

This is the critical conversion moment. The email should communicate:

**Must include:**
- "A buyer is looking for [category] in [location]"
- Number of active RFQs (social proof)
- One-click claim link
- What they get by claiming (RFQ access, free listing, etc.)

**Should NOT include:**
- Pricing (save for after claim)
- Too many details about the platform
- Anything that looks like spam

**Decision needed:** Email template copy. Different from current cold outreach?

---

## 5. Throttling: How do we prevent over-acquisition?

If 10 buyers post Plumbing RFQs in Atlanta the same week, we shouldn't run 10 acquisitions.

**Proposed rules:**
- Cooldown per market: don't re-acquire [category + location] within X days
- Track in `sm_lead_import_batches.metadata_json` or a dedicated table
- Default cooldown: 14 days? 30 days?

**Decision needed:** Cooldown period? Per-category or per-market?

---

## 6. Budget / API credit awareness

DataForSEO charges per API call. Full-location acquisition across 78 categories burns credits fast.

**Proposed guard rails:**
- Daily acquisition budget (max N API calls per day)
- Per-RFQ cap (max 1 acquisition per RFQ, max 30 results per category)
- Alert when budget threshold reached

**Decision needed:** Budget limits? Alert mechanism?

---

## 7. Timing: Sync vs async?

**Option A: Immediate (during RFQ submission)**
- Buyer posts RFQ → acquisition starts in background → vendors emailed within minutes
- Best UX but heaviest on resources

**Option B: Batched (cron job)**
- Cron runs every hour, checks for unmatched RFQs, runs acquisitions in batch
- Lighter on resources, slight delay

**Option C: Hybrid (recommended)**
- Immediate check: do we already have qualified vendors? If yes, email them now
- If not: queue acquisition job, runs within minutes via background worker
- Buyer sees "We're finding vendors for you" status

**Decision needed:** How fast must vendor contact happen after RFQ?

---

## 8. Attribution: Tracking the full funnel

For every vendor who claims and pays, we should be able to trace:

```
RFQ #142 (Plumbing, Atlanta)
  → triggered acquisition batch #87
    → found 30 leads, 18 qualified
      → seeded 18 vendors
        → emailed 18 claim invitations
          → 4 claimed
            → 2 paid for Premium plan
              → Revenue: $700/yr
```

**Already partially built:**
- `sm_vendor_leads.batch_id` links to import batch
- `sm_lead_import_batches.criteria_json` stores category + location
- Missing: link from RFQ → batch (which RFQ triggered this acquisition?)

**Decision needed:** Add `triggered_by_rfq_id` to batch metadata?