> ## Documentation Index
> Fetch the complete documentation index at: https://docs.searchcompany.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Overview

> Architecture for the Add Competitor endpoint

## Purpose

Adds a competitor to analyze in the Explore tab. Scrapes the competitor website using Exa API and stores the data.

## Architecture

```mermaid theme={null}
flowchart TD
    Request["POST /api/explore/add-competitor"]
    
    subgraph validation [Validation]
        CheckLimit["Check user limit (max 2)"]
        CheckDupe["Check for duplicates"]
    end
    
    subgraph scraping [Scraping]
        ExaScraper["scrape_competitor_with_exa()"]
    end
    
    subgraph db [Database]
        Competitors["competitors table"]
    end
    
    subgraph external [External]
        Exa["Exa API"]
    end
    
    Request --> CheckLimit
    CheckLimit --> CheckDupe
    CheckDupe --> ExaScraper
    ExaScraper --> Exa
    Exa --> Competitors
    Competitors --> Response
```

## Request Body

```json theme={null}
{
  "url": "https://competitor.com"
}
```

## Limits

* Users can add up to **2 competitors manually**
* Auto-discovered competitors don't count toward this limit
* Duplicate URLs are rejected

## Response Format

```json theme={null}
{
  "status": "success",
  "competitor": {
    "id": "uuid-...",
    "name": "Competitor Name",
    "url": "https://competitor.com",
    "description": "What they do...",
    "favicon_url": "https://...",
    "source": "user_added"
  }
}
```

## Internal Services

| Service                                            | Purpose                              |
| -------------------------------------------------- | ------------------------------------ |
| [scrape\_competitor\_with\_exa](scrape-competitor) | Scrapes and extracts competitor info |

## Code Location

```
src/app/apis/explore/add_competitor/
├── routes.py
└── exa_scraper.py
```