AI-powered deal qualification and value engineering agent for Vercel enterprise sales.
Enter a URL. In roughly 60 seconds, Lighthouse runs a full pre-sales engineering workflow and delivers an enterprise-ready prospect briefing.
The pipeline executes six stages via a real-time SSE stream:
| Stage | What Happens |
|---|---|
| 1. Fetch | Retrieves the page, captures response headers, and extracts raw HTML for analysis. |
| 2. Tech Stack Detection | Identifies the full composable architecture -- framework, hosting, CDN, CMS, commerce, search, auth, payments, monitoring, analytics, third-party scripts, and rendering strategy. Runs in parallel with performance. |
| 3. Performance Measurement | Queries PageSpeed Insights and Chrome UX Report for lab and real-user metrics (LCP, TTFB, CLS, FID, INP). Runs in parallel with tech stack. |
| 4. Prospect Qualification | Scores the deal 0--100, classifies traffic tier, assesses Vercel fit, and scrapes the careers page for migration signals (frontend hiring, headless mentions, replatform activity). |
| 5. Value Engineering | Models revenue impact with published research citations, builds a TCO comparison, generates a migration plan with risk assessment, maps competitive displacement, matches the closest Vercel case study, and produces audience-segmented talking points. |
| 6. Architecture Design | Generates current-state and target-state Mermaid diagrams, proposes a PoC with measurable success criteria and resource requirements. |
All results are stored in Cortex graph memory for cross-prospect pattern learning, so each new analysis benefits from prior discoveries.
The prospect dashboard renders analysis results across six panels with a deal score header:
+---------------------------------------------------------------+
| <- Back to all prospects |
| example.com [Deal Score: 82] [Immediate] |
+---------------------------------------------------------------+
| | |
| QUALIFICATION | TECH STACK |
| Deal Score: 82/100 | Framework: Next.js 14 (App Router)|
| Traffic: Enterprise | Hosting: AWS CloudFront |
| Vercel Fit: Strong | CMS: Contentful |
| Action: Immediate | Commerce: Shopify |
| Hiring: 3 frontend roles| CDN: CloudFront |
| Headless mentions: Yes | Maturity: partially-decoupled |
| | |
+---------------------------------------------------------------+
| | |
| PERFORMANCE | VALUE ENGINEERING |
| LCP: 3.2s -> 1.8s | Revenue Impact |
| TTFB: 890ms -> 120ms | Conv. lift: +12% |
| CLS: 0.12 | TCO Comparison |
| FID: 45ms | Current: $8,200/mo |
| Overall: Needs Work | Vercel: $5,000/mo |
| | Migration: 6-8 weeks |
| | |
+---------------------------------------------------------------+
| |
| ARCHITECTURE |
| Current State Diagram | Target State Diagram |
| [Mermaid graph TD] | [Mermaid graph TD] |
| |
| PoC Proposal: "Migrate product pages to Next.js on Vercel" |
| Duration: 2 weeks | Success: LCP < 2s, TTFB < 200ms |
| |
+---------------------------------------------------------------+
| |
| TALKING POINTS |
| Engineering | Eng. Leadership | Executive | Finance |
| [Audience-segmented talking points with supporting data] |
| |
+---------------------------------------------------------------+
- Node.js 20+
- npm 9+
- A Google Gemini API key (get one here)
# Clone the repository
git clone https://github.com/michaeldarlington/lighthouse.git
cd lighthouse
# Install dependencies
npm install
# Configure environment variables
cp .env.example .env.localEdit .env.local and add your Gemini API key:
GOOGLE_GENERATIVE_AI_API_KEY=your-gemini-api-key-here# Start the development server (Turbopack)
npm run devOpen http://localhost:3000, enter a URL, and watch the pipeline run.
The core analysis runs through a single POST /api/discover endpoint that streams Server-Sent Events back to the client in real time. Each stage emits running and complete events so the UI can render live progress.
Client Server (POST /api/discover)
| |
|---- POST {url} --------------->|
| |-- Stage 1: Fetch page
|<--- SSE: fetch/running --------|
|<--- SSE: fetch/complete -------|
| |-- Stage 2+3: Parallel
|<--- SSE: techstack/running ----| |-- detectTechStack(html, headers)
|<--- SSE: performance/running --| |-- getPerformanceMetrics(url)
|<--- SSE: techstack/complete ---|
|<--- SSE: performance/complete -|
| |-- Stage 4: qualifyProspect()
|<--- SSE: qualification/complete|
| |-- Stage 5: engineerValue()
|<--- SSE: value/complete -------|
| |-- Stage 6: designArchitecture()
|<--- SSE: architecture/complete-|
|<--- SSE: complete -------------|
| |
| |-- (waitUntil) storeInCortex()
Lighthouse uses Vercel's Fluid Compute (waitUntil from @vercel/functions) to store analysis results in Cortex after the SSE stream closes. The user sees results immediately -- the function instance stays alive in the background to complete the graph storage without adding latency to the response.
Every analysis function (tech stack detection, qualification, value engineering, architecture design) is crash-safe. If an individual stage fails, it returns degraded results rather than crashing the pipeline. The other stages continue running with whatever data is available.
Runs the full analysis pipeline for a given URL. Returns a Server-Sent Event stream.
Request:
{
"url": "https://example.com"
}Response: SSE stream. Each event follows this structure:
data: {"stage": "<stage-name>", "data": {"status": "running"}}
data: {"stage": "<stage-name>", "data": {"status": "complete", "data": {...}}}
Stage names: fetch, techstack, performance, qualification, value, architecture, complete, error.
The final complete event contains the full analysis payload with all six stage results, the domain, URL, and timestamp.
Error responses:
| Status | Body | Condition |
|---|---|---|
400 |
{"error": "Invalid or non-public URL..."} |
URL fails validation |
Configuration: maxDuration = 60 (seconds). The pipeline is optimized to complete within this window.
Returns all previously analyzed prospects from Cortex graph memory.
Response:
{
"nodes": [
{
"title": "example.com",
"body": "...",
"metadata": {
"deal_score": 82,
"traffic_tier": "enterprise",
"recommended_action": "immediate-outreach"
}
}
]
}Returns the full analysis breakdown for a single prospect, grouped by analysis type.
Response:
{
"domain": "example.com",
"prospect": { ... },
"tech_stack": { ... },
"performance": { ... },
"qualification": { ... },
"value_proposition": { ... },
"architecture": { ... },
"case_study_match": { ... },
"migration_steps": [ ... ]
}Returns the Cortex-generated briefing for cross-prospect pattern insights.
Response:
{
"briefing": "...",
"patterns": [ ... ]
}Returns {"error": "Briefing unavailable"} if Cortex has no data for the domain.
| Variable | Required | Default | Description |
|---|---|---|---|
GOOGLE_GENERATIVE_AI_API_KEY |
Yes | -- | Google Gemini 2.5 Flash API key. Powers all AI analysis stages. |
CORTEX_URL |
No | http://localhost:9091 |
Cortex graph memory endpoint for storing and querying prospect data. |
PSI_API_KEY |
No | -- | Google PageSpeed Insights API key. Without it, requests are rate-limited. |
CRUX_API_KEY |
No | -- | Chrome UX Report API key for real-user performance data. The same Google API key works for both PSI and CrUX. |
Create a .env.local file from the provided template:
cp .env.example .env.localLighthouse has 127 tests covering library code, Gemini analysis functions, and integration flows.
# Run all tests
npm test
# Run tests in watch mode during development
npm run test:watch
# Run tests with verbose output and coverage
npx vitest run --reporter=verbose --coverage| Directory | What It Covers |
|---|---|
lib/__tests__/ |
Core library functions -- URL validation, CWV rating, Cortex client, page fetcher, PageSpeed client, Zod schemas, storage pipeline |
lib/gemini/__tests__/ |
AI analysis functions -- tech stack detection, prospect qualification, value engineering, architecture design |
__tests__/integration/ |
End-to-end pipeline flow and data flow validation |
Coverage is collected with @vitest/coverage-v8 and targets lib/**/*.ts. Reports are generated in text, lcov, and json-summary formats.
Current coverage: approximately 94% of library code.
-
Push the repository to GitHub.
-
Import the project in Vercel.
-
Set environment variables in the Vercel dashboard:
Variable Value GOOGLE_GENERATIVE_AI_API_KEYYour Gemini API key CORTEX_URLYour Cortex instance URL PSI_API_KEY(optional) Google PSI key CRUX_API_KEY(optional) Google CrUX key -
Deploy. Vercel auto-detects the Next.js 15 framework.
The POST /api/discover route uses waitUntil from @vercel/functions for background Cortex storage. This requires Vercel's Fluid Compute runtime, which is enabled by default on new deployments. The function's maxDuration is set to 60 seconds to accommodate the full pipeline.
Two GitHub Actions workflows are included:
- ci.yml -- Runs on every push and PR to
main. Executes lint, typecheck, test (with coverage), and build in sequence. - release.yml -- Triggers on
v*tags. Runs the full CI pipeline, then creates a GitHub Release with an auto-generated changelog.
lighthouse/
├── app/
│ ├── layout.tsx Root layout (dark theme, Geist font)
│ ├── page.tsx Landing page (URL input + recent analyses)
│ ├── globals.css Global styles
│ ├── prospects/[domain]/
│ │ ├── page.tsx Prospect dashboard (server component)
│ │ ├── dashboard-content.tsx Dashboard panels (client component)
│ │ ├── loading.tsx Skeleton loading state
│ │ └── error.tsx Error boundary
│ └── api/
│ ├── discover/route.ts SSE streaming pipeline endpoint
│ ├── prospects/route.ts List all analyzed prospects
│ ├── prospects/[domain]/route.ts Full analysis for one prospect
│ └── briefing/[domain]/route.ts Cortex briefing
├── components/
│ ├── url-input.tsx URL input with SSE consumer
│ ├── pipeline-progress.tsx Real-time stage progress tracker
│ ├── prospect-card.tsx Prospect card for grid display
│ ├── deal-score-badge.tsx Color-coded deal score badge
│ ├── cwv-indicator.tsx Core Web Vitals indicator
│ ├── qualification-panel.tsx Deal qualification panel
│ ├── tech-stack-panel.tsx Tech stack + composable architecture map
│ ├── performance-panel.tsx Performance metrics panel
│ ├── value-engineering-panel.tsx Revenue impact + TCO + migration panel
│ ├── architecture-panel.tsx Mermaid diagrams + PoC proposal
│ ├── talking-points-panel.tsx Audience-segmented talking points
│ └── ui/ shadcn/ui primitives
├── lib/
│ ├── utils.ts URL validation, CWV rating, formatting
│ ├── cortex.ts Cortex HTTP client
│ ├── cortex-store-pipeline.ts Bulk storage pipeline
│ ├── fetcher.ts Resilient page fetcher
│ ├── pagespeed.ts PSI + CrUX client
│ ├── schemas.ts Zod schemas (TechStack, Qualification,
│ │ ValueEngineering, Architecture)
│ └── gemini/
│ ├── index.ts Barrel export
│ ├── detect-tech-stack.ts Composable architecture detection
│ ├── qualify-prospect.ts Deal qualification + careers scraping
│ ├── engineer-value.ts Revenue impact + TCO + migration
│ └── design-architecture.ts Current/target diagrams + PoC
├── __tests__/integration/ Integration tests
├── .github/workflows/
│ ├── ci.yml Lint, typecheck, test, build
│ └── release.yml CI + GitHub Release on v* tags
├── vitest.config.ts Test configuration
├── next.config.ts Next.js configuration
├── .env.example Environment variable template
└── package.json
| SA Responsibility | How Lighthouse Handles It |
|---|---|
| Prospect research | Automated URL analysis replaces hours of manual research. Tech stack, performance, and company profile are extracted in under 60 seconds. |
| Technical discovery | Composable architecture detection identifies the full stack -- framework, hosting, CDN, CMS, commerce, auth, payments, monitoring -- with confidence levels and evidence. |
| Deal qualification | Structured scoring (0--100) with traffic tier classification, Vercel fit assessment, migration signal detection, and a recommended next action. |
| Value proposition | Revenue impact modeling with published research citations, TCO comparison, and quantified performance improvement projections. |
| Competitive positioning | Competitive displacement analysis with key differentiators and pre-built objection handling for the incumbent provider. |
| Architecture design | Current-state and target-state Mermaid diagrams with annotated changes and benefits. |
| PoC scoping | Structured PoC proposal with scope, duration, success criteria, and resource requirements from both sides. |
| Stakeholder communication | Audience-segmented talking points for engineering, engineering leadership, executive, and finance stakeholders. |
| Case study matching | Automated matching to the most relevant Vercel case study with similarity rationale and key outcomes. |
| Knowledge management | Cortex graph memory stores every analysis for cross-prospect pattern learning and briefing generation. |
| Technology | Purpose |
|---|---|
| Next.js 15 (App Router, TypeScript) | Full-stack React framework with server and client components |
| Tailwind CSS 4 + shadcn/ui | Styling and UI component system |
| Vercel AI SDK + Google Gemini 2.5 Flash | Structured AI output for all analysis stages |
| Cortex | Graph memory for prospect storage and cross-analysis pattern learning |
| Google PageSpeed Insights | Lab performance metrics |
| Chrome UX Report | Real-user performance data |
| Vercel Fluid Compute | waitUntil for background storage without blocking the response |
| Zod | Schema validation for all AI-generated structured output |
| Mermaid | Architecture diagram rendering |
| Vitest | Test framework with V8 coverage |
| GitHub Actions | CI/CD pipeline |
MIT