SignalForge

Live competitive intelligence, forged from the web.

Features · Architecture · Tech stack · Quick start · Deployment · Demo accounts

---

About

SignalForge is a full-stack competitive intelligence platform built for the Web Data UNLOCKED Hackathon (Bright Data × lablab.ai). It monitors competitors across pricing, messaging, hiring, and news—using real-time web data from Bright Data—and surfaces actionable change events in a modern dashboard.

Forge Scout, the built-in AI agent, researches competitors via Bright Data MCP (SERP + scrape) orchestrated with LangGraph—no stale training data, only live web signals.

Track: GTM Intelligence — pricing moves, positioning shifts, hiring velocity, and news for go-to-market teams.

---

Features

Area	What it does
Competitor monitoring	Add competitors with sources (pricing, homepage, careers, news)
Bright Data collection	SERP API, Web Scraper, Web Unlocker zones; MCP fallback pipeline
Change detection	Snapshot diff engine emits structured events with severity
Forge Scout agent	LangGraph + Bright Data MCP: search, scrape, synthesize intel
Event feed & charts	Filterable timeline, overview metrics, daily brief
Alert rules	Configurable rules evaluated on new events
Scheduler	APScheduler runs autonomous collection on an interval
Auth & demo mode	JWT sessions; demo account with read-only + agent quota
Demo toolkit	Simulate HTML changes for live demos without waiting on crawls

---

Architecture

flowchart LR
  subgraph Frontend["frontend/ · Vercel"]
    UI[React Dashboard]
  end

  subgraph Backend["app/ · FastAPI Cloud"]
    API[FastAPI API]
    COL[Collectors]
    DIFF[Diff Engine]
    AGT[Forge Scout · LangGraph]
    SCH[APScheduler]
  end

  subgraph Data["Storage"]
    DB[(SQLite / Neon PostgreSQL)]
  end

  subgraph BrightData["Bright Data"]
    SERP[SERP API]
    SCR[Web Scraper]
    UNL[Web Unlocker]
    MCP[MCP Server]
  end

  UI -->|REST / JWT| API
  API --> COL
  COL --> SERP
  COL --> SCR
  COL --> UNL
  COL --> MCP
  AGT --> MCP
  COL --> DIFF
  DIFF --> DB
  API --> DB
  SCH --> COL

Loading

---

Tech stack

Backend (app/)

Technology	Role
FastAPI	REST API, OpenAPI docs, middleware
SQLAlchemy	ORM — competitors, snapshots, events, alerts
SQLite / Neon PostgreSQL	Local dev vs production database
Bright Data	SERP, Scraper, Unlocker REST + MCP SSE
LangGraph	Forge Scout agent workflow
langchain-mcp-adapters	MCP tool integration
BeautifulSoup + lxml	HTML extraction
APScheduler	Scheduled collection jobs
PyJWT	Bearer token authentication
Pydantic Settings	Environment configuration

Frontend (frontend/)

Technology	Role
React 19	Dashboard UI
TypeScript	Type-safe components
Vite 8	Dev server & production build
Recharts	Overview charts & metrics
react-markdown + remark-gfm	Forge Scout rendered responses

Infrastructure

Service	Use
FastAPI Cloud	Backend hosting
Vercel	Frontend hosting

---

Project structure

.
├── app/                 # FastAPI backend (API, collectors, agents, scheduler)
├── frontend/            # React + Vite dashboard
├── docs/                # README cover (signalforge-cover-16x9.png)
├── schemas/             # pulse_events JSON schema
├── data/                # SQLite (local) + runtime settings
├── fixtures/            # Demo HTML for simulate-change
├── scripts/             # CLI helpers
├── requirements.txt
├── pyproject.toml
└── .env.example

---

Quick start

Prerequisites

• Python 3.12+
• Node.js 20+
• Bright Data API token (and optional MCP URL) for live collection

1. Backend

python -m venv .venv
source .venv/bin/activate   # Windows: .venv\Scripts\activate
pip install -r requirements.txt
cp .env.example .env
# Edit .env — set BRIGHTDATA_API_TOKEN, BRIGHTDATA_MCP, DATABASE_URL, auth secrets
python run_api.py

• API: http://localhost:8000
• Docs: http://localhost:8000/docs

2. Frontend

cd frontend
npm install
npm run dev

• App: http://localhost:5173 (Vite proxies /api to the backend in dev)

Optional frontend/.env.local:

VITE_API_URL=http://127.0.0.1:8000/api/v1

---

Deployment

Backend → FastAPI Cloud

pip install "fastapi[standard]"
fastapi login
fastapi deploy

Set environment variables from .env.example in the dashboard. Use Neon DATABASE_URL for production PostgreSQL.

• Entrypoint: app.main:app ([tool.fastapi] in pyproject.toml)

Frontend → Vercel

1. Import repository — Root Directory: frontend
2. Framework: Vite (vercel.json included)
3. Environment: VITE_API_URL=https://<your-api-host>/api/v1

---

Environment variables

See .env.example for the full list. Key values:

Variable	Description
BRIGHTDATA_API_TOKEN	Bright Data API key
BRIGHTDATA_MCP	MCP SSE URL (Forge Scout + MCP fallback)
BRIGHTDATA_SERP_ZONE / SCRAPER_ZONE / UNLOCKER_ZONE	REST zone names
DATABASE_URL	sqlite:///./data/pulse.db or Neon PostgreSQL URL
COLLECTOR_MODE	brightdata (default) or local for HTTP-only demo
SCHEDULER_ENABLED	Autonomous collection on/off
AUTH_*	JWT login, demo user, token expiry

---

Demo accounts

Role	Username	Password	Notes
Demo	demo	demo	Read-only competitors; 5 Forge Scout requests

Change credentials before any public deployment.

---

Bright Data integration

SignalForge uses Bright Data across the stack:

1. REST collectors — SERP for news signals, Web Scraper for pages, Web Unlocker for protected sites
2. MCP pipeline — Fallback when zones fail; primary path for Forge Scout (search_engine, scrape_as_markdown)
3. LangGraph agent — Plans queries, runs MCP tools, returns cited competitive intel

References: Bright Data AI Agents · MCP Server

---

Hackathon submission

Item	Details
Event	Web Data UNLOCKED
Organizer	Bright Data × lablab.ai
Project	SignalForge — GTM / competitive intelligence
Live web data	Bright Data SERP, Scraper, Unlocker, MCP
AI agent	Forge Scout (LangGraph + MCP)

---

Team & license

Built for Web Data UNLOCKED (May 2026). Replace this section with your team names and repository links before final submission.