Documentation

Learn how CompeteScope works and how to use it effectively

What is CompeteScope?

CompeteScope is a competitive intelligence platform built for technical leaders. It automatically gathers, analyzes, and synthesizes competitor information into actionable intelligence briefs.

Instead of spending hours manually researching competitors, CompeteScope uses AI-powered agents to crawl competitor websites, extract key information, and generate comprehensive analysis reports.

Key Features

Automated Intelligence Gathering

Firecrawl-powered web scraping extracts pricing, features, tech stack, and more from competitor sites.

AI-Powered Analysis

LLM analysis identifies threats, opportunities, and competitive signals from raw data.

Gap Analysis

Compare your company against competitors to identify what you lack and where you excel.

Interactive Chat

Ask questions about your competitive intelligence using natural language.

PDF Upload

Upload competitor documents, pitch decks, or reports for additional context.

Executive Briefs

Auto-generated reports ready to share with your team or stakeholders.

Signal Types

CompeteScope identifies various competitive signals categorized by threat level:

HIGH THREAT

Critical competitive moves requiring immediate attention - major product launches, funding rounds, key hires.

MEDIUM THREAT

Notable activities to monitor - feature updates, pricing changes, partnership announcements.

OPPORTUNITY

Gaps or weaknesses you can exploit - missing features, negative sentiment, underserved segments.

System Architecture

CompeteScope uses a pipeline-based architecture where each analysis progresses through distinct stages:

USER INPUT DATA GATHERING ANALYSIS OUTPUT | | | | v v v v +--------+ +----------+ +-----------+ +----------+ +----------+ +---------+ | | | | | | | | | | | | | CREATE |--->| QUEUED |--->| GATHERING |--->| ANALYZING|--->| GENERATING|--->| COMPLETE| | | | | | | | | | | | | +--------+ +----------+ +-----------+ +----------+ +----------+ +---------+ | | | | | | | | | | | | v v v v v v 0% 0-5% 5-55% 55-70% 70-95% 100%

Pipeline Stages Explained

1. QUEUED (0-5%)

Pipeline created and waiting to start. Initial setup and validation.

2. GATHERING (5-55%)

Firecrawl agent crawls competitor websites, extracting product info, pricing, tech stack, team data, and more.

3. ANALYZING (55-70%)

LLM processes raw data to generate competitor profiles, threat/opportunity scores, and competitive signals.

4. GENERATING (70-95%)

Creates the executive brief, gap analysis (if comparative mode), and final report formatting.

5. COMPLETE (100%)

Report ready for viewing. Chat interface enabled for interactive Q&A.

Data Flow

+------------------+ | FIRECRAWL | Competitor URLs | Web Scraping |---------------------------+ +------------------+ | v +------------------+ +-------------+ | REDUCTO | PDF Upload | | | PDF Parser |------------------>| SUPABASE | +------------------+ | Database | | | +------------------+ +------+------+ | OPENROUTER | | | LLM Analysis |<-------------------------+ +------------------+ | | | v v +------------------+ +-------------+ | Competitor | | Signals | | Profiles | | & Brief | +------------------+ +-------------+ | | +----------------+--------------------+ | v +-------------+ | REPORT | | Dashboard | +-------------+

Tech Stack

Backend

  • FastAPI (Python)
  • Supabase (PostgreSQL + Auth)
  • Pydantic schemas

AI/ML

  • OpenRouter (LLM gateway)
  • Claude/GPT models
  • Structured output parsing

Data Gathering

  • Firecrawl (web scraping)
  • Reducto (PDF parsing)

Frontend

  • Jinja2 templates
  • Tailwind CSS
  • Chart.js

Getting Started

Follow these steps to create your first competitive intelligence report:

Step 1: Create a New Analysis

  1. Click "+ New Analysis" in the navigation bar
  2. Enter a name for your analysis (e.g., "Q1 2025 Competitor Review")
  3. Add competitor URLs - enter the main website URL for each competitor
  4. Optional: Enable Comparative Mode by entering your company name to get gap analysis
  5. Click "Start Analysis" to begin

Step 2: Monitor Progress

After starting, you'll see a progress modal showing the pipeline status:

Gathering intelligence from competitor websites...
Analyzing competitor data...
Generating executive brief...

Analysis typically completes in 2-5 minutes depending on the number of competitors.

Step 3: Review Your Report

Once complete, you'll be redirected to the report view with several tabs:

  • Overview - Summary statistics, threat matrix, top signals
  • Signals - All detected competitive signals with filtering
  • Competitors - Detailed profiles for each competitor
  • Brief - Executive summary document
  • Chat - Ask questions about the intelligence
  • Raw Data - Full JSON data for each competitor

Step 4: Upload Additional Documents

Enhance your analysis by uploading competitor documents:

  1. From the dashboard, click the upload icon on a pipeline card
  2. Select PDF files (pitch decks, whitepapers, reports)
  3. Documents are parsed and added to the intelligence context
  4. The chat interface will have access to this additional information

Step 5: Use the Chat Interface

The chat feature lets you interactively explore your competitive intelligence:

Example questions:

  • "What are the biggest threats from Competitor X?"
  • "Compare pricing strategies across all competitors"
  • "What features do competitors have that we don't?"
  • "Summarize hiring trends in the market"

Tips for Best Results

  • Use main website URLs - The scraper works best with the primary domain (e.g., competitor.com, not competitor.com/pricing)
  • Include 3-5 competitors - Enough for meaningful comparison without overwhelming the analysis
  • Enable Comparative Mode - Gap analysis is most valuable when comparing against your own company
  • Upload relevant PDFs - Pitch decks and product docs add valuable context
  • Use specific chat questions - The more specific your question, the better the answer

API Endpoints

CompeteScope exposes a REST API for programmatic access. All endpoints require authentication via session cookies.

Pipelines

POST /api/pipelines/

Create a new analysis pipeline

Request Body 
{
  "name": "Q1 Competitor Analysis",
  "competitors": ["https://competitor1.com", "https://competitor2.com"],
  "host_company": "My Company"  // optional, enables comparative mode
}
POST /api/pipelines/{id}/start

Start a queued pipeline

Response 
{
  "status": "processing",
  "message": "Pipeline started"
}
GET /api/pipelines/

List all pipelines for the authenticated user

Response 
[
  {
    "id": "uuid",
    "name": "Analysis Name",
    "status": "complete",
    "progress": 100,
    "competitors": ["url1", "url2"],
    "created_at": "2025-01-31T..."
  }
]
GET /api/pipelines/{id}/detailed-status

Get detailed progress for polling during analysis

Response 
{
  "status": "processing",
  "progress": 45,
  "stage": "gathering",
  "stage_detail": "Scraping competitor2.com...",
  "competitors_completed": 1,
  "competitors_total": 3
}
DELETE /api/pipelines/{id}

Delete a pipeline and all associated data

Chat

POST /api/chat/{pipeline_id}/messages/stream

Send a message and receive streaming response (SSE)

Request Body 
{
  "content": "What are the main threats from competitors?"
}
Response (SSE stream) 
data: {"token": "The"}
data: {"token": " main"}
data: {"token": " threats"}
...
data: {"done": true, "suggested_questions": [...]}
GET /api/chat/{pipeline_id}/messages

Get chat history for a pipeline

GET /api/chat/{pipeline_id}/suggestions

Get suggested questions based on the report content

Upload

POST /api/upload/{pipeline_id}

Upload a PDF document to enhance analysis

Request 
Content-Type: multipart/form-data

file: (PDF file)
Response 
{
  "status": "success",
  "document_id": "uuid",
  "pages_processed": 12
}

Authentication

Authentication is handled via Supabase Auth with session cookies. The API uses access_token and refresh_token cookies set during login.

POST /auth/login

Magic link login (sends email)

POST /auth/logout

Clear session and logout