# Query Fan-Out Analysis Tool A Query Fan-Out analysis tool similar to iPullRank's Qforia. This tool generates AI-powered query expansions across 6 intent types and validates them with real-time search data. ## Features - **Query Expansion**: Generate 25+ query variations using Gemini 2.0 Flash - **6 Intent Types**: Reformulation, Related, Implicit, Comparative, Entity Expansion, Personalized - **Real-time Validation**: Validate top queries with Perplexity's Sonar Pro - **Interactive Visualization**: D3.js force-directed graph with drag, zoom, and tooltips - **Results Table**: Filter, sort, search, copy, and export to CSV - **Async Processing**: Background job processing with polling ## Tech Stack - **Backend**: FastAPI (Python 3.12) - **Frontend**: React + TypeScript + Vite - **Visualization**: D3.js force-directed graph - **Styling**: Tailwind CSS - **AI Models**: - Gemini 2.0 Flash (query expansion) - Perplexity Sonar Pro (validation) - **Database**: Supabase PostgreSQL ## Prerequisites - Python 3.12+ - Node.js 20+ - API keys for: - Google AI (Gemini) - Perplexity - Supabase project ## Setup ### 1. Clone and install dependencies ```bash # Backend cd backend pip install -r requirements.txt # Frontend cd frontend npm install ``` ### 2. Configure environment variables Backend (`backend/.env`): ```env GEMINI_API_KEY=your_gemini_api_key PERPLEXITY_API_KEY=your_perplexity_api_key SUPABASE_URL=https://your-project.supabase.co SUPABASE_KEY=your_supabase_anon_key ENVIRONMENT=development ``` Frontend (`frontend/.env`): ```env VITE_API_URL=http://localhost:8000 ``` ### 3. Set up Supabase database Run the SQL migration in your Supabase SQL Editor: ```sql -- See supabase/migrations/001_create_query_results.sql ``` ### 4. Run the development servers ```bash # Terminal 1: Backend cd backend uvicorn main:app --reload --port 8000 # Terminal 2: Frontend cd frontend npm run dev ``` Visit `http://localhost:3000` to use the application. ## Docker Deployment ```bash # Production docker-compose up --build # Development with hot reload docker-compose -f docker-compose.dev.yml up --build ``` ## API Endpoints | Method | Endpoint | Description | |--------|----------|-------------| | GET | `/health` | Health check | | POST | `/api/analyze` | Start query analysis job | | GET | `/api/results/{job_id}` | Get job results | | GET | `/api/recent` | List recent queries | ### POST /api/analyze Request: ```json { "query": "best project management software for startups", "max_queries": 25 } ``` Response: ```json { "job_id": "uuid", "status": "processing" } ``` ## Query Types | Type | Description | Color | |------|-------------|-------| | Reformulation | Direct rephrasings | Blue | | Related | Logically connected questions | Green | | Implicit | Unstated intents (pricing, reviews) | Amber | | Comparative | Competitor comparisons | Red | | Entity Expansion | Specific components/features | Purple | | Personalized | Context-specific adaptations | Pink | ## Project Structure ``` . ├── backend/ │ ├── main.py # FastAPI app │ ├── config/ │ │ └── settings.py # Environment config │ ├── src/ │ │ └── services/ │ │ ├── gemini_service.py # Query expansion │ │ ├── perplexity_service.py # Validation │ │ └── database_service.py # Supabase CRUD │ ├── requirements.txt │ └── Dockerfile ├── frontend/ │ ├── src/ │ │ ├── App.tsx # Main app │ │ ├── components/ │ │ │ ├── NetworkGraph.tsx # D3 visualization │ │ │ ├── ResultsTable.tsx # Data table │ │ │ └── ErrorBoundary.tsx # Error handling │ │ ├── lib/ │ │ │ └── api.ts # API client │ │ └── types/ │ │ └── index.ts # TypeScript types │ ├── package.json │ └── Dockerfile ├── supabase/ │ └── migrations/ │ └── 001_create_query_results.sql ├── docker-compose.yml └── README.md ``` ## License MIT # SeoLLM