# Plan: Market Research Agent for Solo Founders

## Context
Build a local demo of an AI agent that helps solo founders discover their next product idea. The founder describes their situation in natural language; the agent conducts one-shot market research via web search and delivers an interactive dashboard report.

## Requirements Summary

| Aspect | Decision |
|--------|----------|
| **Frontend** | React SPA (Vite) |
| **Backend** | FastAPI (Python) |
| **User Input** | Natural language prompt |
| **Data Sources** | Web search (DuckDuckGo, no API key), social signals via search |
| **Output** | Interactive dashboard with collapsible sections |
| **Research Style** | One-shot (~30-60s), parallel sub-searches + LLM synthesis |
| **LLM** | Kimi K3 via Moonshot Anthropic-compatible endpoint |

## Architecture

```
┌─────────────┐     POST /research     ┌─────────────┐
│  React SPA  │ ─────────────────────► │  FastAPI    │
│  (Vite)     │                        │  Backend    │
│             │ ◄── JSON Report ────── │             │
└─────────────┘                        └──────┬──────┘
                                              │
                       ┌──────────────────────┼──────────────────────┐
                       ▼                      ▼                      ▼
                ┌─────────────┐       ┌─────────────┐       ┌─────────────┐
                │ DuckDuckGo  │       │ DuckDuckGo  │       │ DuckDuckGo  │
                │ Trends      │       │ Competitors │       │ Pain Points │
                └─────────────┘       └─────────────┘       └─────────────┘
                       │                      │                      │
                       └──────────────────────┼──────────────────────┘
                                              ▼
                                       ┌─────────────┐
                                       │  Kimi K3    │
                                       │  Synthesis  │
                                       └─────────────┘
```

## Report Structure (Dashboard Sections)

1. **Executive Summary** — Top-level takeaways and recommended focus areas
2. **Industry Trends** — What's growing, declining, or emerging in the space
3. **Competitor Landscape** — Key players, funding stage, positioning
4. **Existing Products** — Products solving related problems, with feature summaries
5. **Pain Points & Limitations** — What users complain about (from social signals)
6. **Market Gaps & Opportunities** — Unserved niches or under-served segments
7. **Recommended Next Steps** — Actionable ideas for the founder to validate

## Research Agent Flow

1. **Query Decomposition** — LLM breaks the founder's prompt into 3-5 parallel search queries
2. **Parallel Search** — Each query runs through DuckDuckGo independently
3. **Result Aggregation** — Deduplicate and rank results by relevance
4. **Synthesis Pass** — LLM analyzes aggregated data and produces structured report JSON
5. **Response** — Backend returns structured JSON; frontend renders interactive dashboard

## Tech Stack Details

### Backend (`backend/`)
- **Framework:** FastAPI with uvicorn
- **Search:** `duckduckgo-search` Python library (free, no API key)
- **LLM Client:** `anthropic` SDK with `ANTHROPIC_BASE_URL` override to Moonshot
- **Data:** In-memory storage (research sessions keyed by UUID)
- **Key Files:**
  - `main.py` — FastAPI app, CORS, routes
  - `agent.py` — Research orchestration (decompose → search → synthesize)
  - `search.py` — DuckDuckGo search wrapper with rate limiting
  - `models.py` — Pydantic models for request/response

### Frontend (`frontend/`)
- **Framework:** React 18 + Vite
- **Styling:** Tailwind CSS (or plain CSS for speed)
- **Key Components:**
  - `PromptInput` — Natural language textarea with examples
  - `ResearchDashboard` — Report layout with collapsible sections
  - `SectionCard` — Reusable card for each report section
  - `LoadingState` — Progress indicator during research
- **Key Files:**
  - `src/App.jsx` — Main layout, routing
  - `src/components/PromptInput.jsx`
  - `src/components/ResearchDashboard.jsx`
  - `src/api.js` — Fetch wrapper for `/research`

## Critical Design Decisions

1. **DuckDuckGo over paid APIs** — Zero API keys needed for demo. Can swap to Serper.dev/Tavily later.
2. **No database** — Research sessions stored in-memory. Simple for demo; add SQLite if history is needed.
3. **Streaming response** — FastAPI streams partial results so the dashboard populates incrementally (better UX for 30-60s wait).
4. **One-shot vs. multi-turn** — Strictly one-shot. No follow-up questions from the agent to keep it fast.

## Verification Plan

1. Start backend: `cd backend && uvicorn main:app --reload`
2. Start frontend: `cd frontend && npm run dev`
3. Open `http://localhost:5173`, enter a prompt like:
   > "I'm a solo developer with $50k budget, interested in B2B SaaS for the construction industry. I have React and Python skills."
4. Verify dashboard renders with all 7 sections populated.
5. Verify research completes in under 60 seconds.

## Open Questions

- Should research sessions be persisted to disk (SQLite) so reports survive server restarts?
- Should the dashboard allow exporting to PDF/Markdown?
- Should the agent suggest adjacent/nearby markets if the primary market looks saturated?