React Integration Guide

Replaces prior handoffs (REACT_IMPLEMENTATION_GUIDE.md, REACT_BOT_INSTRUCTIONS.md, REACT_REQUIREMENTS.md). This version focuses on what the UI must do and which fields to surface.

End-to-End Flow

1. Submit URL – call POST /run with url and project_id. Capture run_id from the 202 response.
2. Poll status – hit GET /run/{run_id}/status every 2 s. When status === "awaiting_category_confirmation", move to Step 2.
3. Customize categories – render the enrichment payload and collect user edits.
4. Confirm – POST /run/{run_id}/confirm-categories with the final payload. Move the UI to a loading state while status becomes harvesting_keywords.
5. Display results – continue polling until status === "complete", then show the harvested keyword payload.

Reference diagrams: docs/reference/flows.md.

Required Screens & Responsibilities

Step 1 – URL Submission

• Collect url and optionally project_id.
• Handle request errors (network, validation). Show inline feedback.
• When successful, persist run_id and start polling.

Step 2 – Category Confirmation UI

• Source data: status.enrichment.
• Show:
  • business_type, business_focus, high_level_categories, seed_keywords.
  • Type-specific editors (see table below).
• Call /admin/business-types (GET) to populate selectors for business type/business focus if needed.
• Validate before POST:
  • At least one category.
  • local requires ≥1 location (limit to 5).
  • Warn (but allow) empty app_names for saas, game, marketplace.
• POST body:

  {
    "confirmed_categories": ["communication", "integration"],
    "updated_business_focus": "...",
    "locations": ["Boston"],
    "app_names": ["Slack"]
  }

• Handle 400 responses by showing backend message verbatim.

Step 3 – Harvest Progress + Results

• Loading state: show spinner + copy while status is harvesting_keywords.
• Final state: status.harvest includes:
  • by_category[{category}].keywords[] with { keyword, score, sources, brand_flag, dataforseo_category_paths }.
  • total_keywords, optional errors, timestamps.
• Provide export (CSV, copy) and jump-to-category UX.
• Surface warnings if harvest.errors exists.

Data to Surface in UI

• primary_intent, secondary_intents, intent_confidence.
• sources (array including domain_seed, harvest_ai).
• brand_flag, original_keyword_text, latest_trend.
• dataforseo_category_paths for context chips.
• React dashboard should display run-level metadata (business_focus, business_type, timestamps).

Type-Specific Inputs

Business type	Required fields	UX notes
local	locations[] (1–5)	chips or pill inputs; enforce unique entries.
saas, game, marketplace	app_names[] (optional but recommended)	Show inline reminder if empty.
ecommerce	Optionally gather product categories	Use multi-select if available.
service, content	No additional inputs	Keep UI minimal.

Error Handling Patterns

• Network failure: keep previous state, show toast, allow retry.
• 404/expired run: prompt to restart Step 1.
• failed status: show status.error (if present) and contact instructions.
• Always continue polling after recoverable errors to avoid stale state.

Diagnostics & Admin Utilities (Optional)

• /diagnostics/run/\{runId\} – helpful for debugging stuck harvests.
• /diagnostics/keyword?keyword=foo – look up canonical keyword metadata.
• /diagnostics/dataforseo-category?id=123 – confirm taxonomy mapping.
• Provide quick links in an internal admin panel if desired.

Related References

• Backend lifecycle: docs/backend.md
• Endpoint details: docs/reference/endpoints.md
• Schema fields and ClickHouse usage: docs/reference/schema.md
• Data architecture rationale: docs/data-architecture.md