# Ace Pitch Engine V2 — Master Build Brief (Personal Tool, From Scratch)

## Context for Claude
This is a personal lead-generation and cold-outreach tool for one operator (Ace Digitals Global). It is NOT a SaaS, NOT multi-tenant, and NOT for production/commercial resale. Being built from scratch — do not assume any existing codebase to preserve. Hosted on a personal VPS, deployed to a custom domain, pinged by UptimeRobot. No GitHub (do not assume a GitHub remote exists or is wanted). Built and directed via claude.ai chat, one phase per conversation.

## What it does
Search for local businesses without websites or with weak digital presence → score them on real evidence → generate a personalized, non-salesy outreach email and PDF audit → send it → let the operator log what the client says in reply → regenerate a sharper pitch grounded in that reply, never guessing.

## Hard rules for every phase
- No authentication, no multi-user support, no team features. One operator, no login system needed beyond a simple env-var API key if the app is reachable from the open internet.
- No fabricated data, ever. Every score, claim, or "finding" must trace to something the code actually retrieved. If data isn't available, say so in the UI — don't invent it.
- Do not build CRM-scale infrastructure (no entity-relationship timeline system, no access control, no pagination-at-scale). This is a single-user tool — a straightforward relational schema is enough.
- Preserve history, don't overwrite it: research versions and generated pitches/PDFs should stack, not replace.
- Every session must end by updating `BUILD_LOG.md` in the repo root: what was completed, what's next, any open decisions. Every new session starts by reading it. This is not optional — it's what prevents hallucinated continuation after a reset.
- Stop and ask (don't guess) whenever: an API behaves unexpectedly, a design decision isn't covered by this brief, or a phase's scope is ambiguous.

## Stack
- Node.js / Express (matches operator's existing familiarity)
- SQLite (single-user; no need for Postgres/hosted DB complexity)
- SerpApi — primary search/discovery provider (Google Maps, email lookup)
- Apify — secondary provider for multi-source research (Yelp, Yellow Pages, other directories) once Phase 2 begins
- OpenAI — structured extraction, scoring, classification, JSON output
- Anthropic (Claude) — pitch narrative, angle selection, executive/PDF writing
- PDFKit — PDF generation
- Resend or nodemailer — sending
- MX/domain-record check library — email verification before send

## Phase plan (build one phase per chat/session)

**Phase 1 — Foundation**
SQLite schema (businesses, research_versions, pitches, pdfs, sends, client_notes). Basic Express scaffold. SerpApi search → score → store pipeline, ported cleanly from the scoring logic already proven to work (no-website detection, review sweet spot, rating thresholds, free-email detection). Health check endpoint for UptimeRobot. Deployable to the VPS.

**Phase 2 — Research depth**
Apify integration as a secondary source. Duplicate detection/merge (name + phone + website + address matching, uncertain matches flagged for manual review). Evidence-based opportunity scoring refined to show its factors.

**Phase 3 — AI + Pitch**
Dual-AI orchestration (OpenAI for structuring/scoring, Anthropic for pitch narrative). Conversational Pitch Engine: angle selection based on evidence (no site / weak reviews / citation conflict / already strong — pick a different angle per case), avoiding the "no website" cold-email cliché as the only opening. Client Notes field per business + AI extraction pass (URL detected, objection noted, interest level) — manual trigger, not automatic pipeline.

**Phase 4 — Reliability**
Research cache (don't re-research a business researched recently). Search resume/checkpoint for large batch searches. Email verification (MX/domain check) before send. Lightweight spam-word flag pass on generated copy (warn, don't block).

**Phase 5 — Polish**
PDF versioning (old PDFs stay accessible). Minimal UI for notes, chosen pitch angle, and duplicate-review queue.

## What's explicitly OUT of scope
Auth/Google Sign-In, PWA polish, Prompt Studio UI, Business Rules Engine UI, Knowledge Base module, notification system, global search, watch lists, analytics dashboards, archive/retention tiers, provider health dashboard, full CRM conversation timeline with entity relationships and access control.