Internal Technical Reference · v1.0 · April 2026
BrandLift.ai
Technical Overview & Architecture Guide
This document covers every technology used in the BrandLift platform — what it does, why it was chosen, how the components connect, and where the stack is heading. Written for onboarding engineers, outsourced support staff, and technical stakeholders.
Section 01
What is BrandLift?
BrandLift is an AI-powered local business acquisition and web presence platform. It automates the entire journey from finding a small business online to converting them into a paying hosted website client — with minimal human intervention at each step.
Find
Scrape Google SERPs and directories for local businesses in target industries and cities. Score and rank them by how bad their digital presence is.
Audit
Run a 5-category, 20-signal SEO audit on every discovered business. Score technical, on-page, content, local, and trust signals against a BrandLift benchmark.
Propose
Generate a personalized proposal page — a "forensic audit report" — with before/after comparisons, branding tools, domain search, and pricing. Deliver via cold email.
Convert
Proposal → Stripe checkout → provisioned hosting slot → live website editor. Client gets a branded site, portal access, and ongoing billing — all managed in-platform.
The admin team never touches cold outreach manually. The system discovers, enriches, audits, emails, and tracks responses automatically. Human review happens only at the reservoir release stage — deciding which leads to dispatch proposals to.
Section 02
System Architecture
The platform is a single Next.js application that acts as both the admin control plane and the client-facing web layer. External services are consumed via API — no microservices, no separate worker processes (except the scraper relay on Retina).
Internet
brandlift.ai
Apex domain — admin + portal
*.brandlift.ai
Vanity subdomains → proposal pages
Edge
Nginx
TLS termination, reverse proxy → :3001, static asset bypass
Next.js Middleware
Subdomain → /portal/proposal/{sub} rewrite, x-pathname header
App
Next.js 14 (PM2)
200+ API routes + React pages, port 3001, single fork
Admin Layer
/admin/* — 25 admin pages, reservoir, proposals, settings
Client Portal
/portal/* — dashboard, billing, editor, proposal
Data
MySQL (localhost)
Primary datastore — leads, proposals, accounts, events
Prisma ORM
Type-safe queries, schema migrations, v5
Local filesystem
/public/ — generated logos, template previews, vault assets
Remote nodes
Retina (187.124.243.5)
Template vault, scraper relay, Ghost server
Muscle (187.124.95.147)
WordPress showroom vault, golden master provisioning
External APIs
Google AI
Gemini 2.5 Flash, Imagen 3, PageSpeed, Places
Outreach
Apollo, Instantly, Hunter, Twilio
Commerce
Stripe, Hostinger, Oxylabs
Section 03
Technology Stack
Core Framework
| Technology | Version | What It Does | Why We Use It |
|---|---|---|---|
| Next.js | 14.1 | Full-stack React framework — API routes, SSR, middleware, static assets in one deployment. | Eliminates separate backend. App Router enables true Server Components, reducing client bundle size on data-heavy admin pages. |
| React 18 | 18.2 | UI component library. Runs server-side (RSC) and client-side with concurrent rendering. | Server Components let the 1,600-line Lead Reservoir page run entirely server-side — zero hydration cost for read-only data. |
| TypeScript | 5.3 | Statically typed JavaScript. Catches errors at compile time across 200+ API routes. | At 50,000+ lines, type safety is non-negotiable. Refactors that would silently break 30 files in plain JS are caught immediately. |
Data Layer
| Technology | Role | Why |
|---|---|---|
| MySQL | Primary relational database on localhost:3306. Stores all leads, proposals, accounts, email events, and site data. | Battle-tested for structured relational data. 30+ models with FK relationships benefit from SQL JOIN performance. Free on self-hosted VPS. |
| Prisma ORM v5 | Database client and schema manager. Generates TypeScript types from schema, handles migrations. | Eliminates SQL injection bugs and runtime type errors. Schema is single source of truth — change schema, all query types update automatically. |
AI & Intelligence
| Service | Model | Used For | Why |
|---|---|---|---|
| Google Gemini | gemini-2.5-flash | Taglines, SEO copy, proposal text, email subjects, crawler prompt optimization, OpenClaw extraction. | Flash tier balances speed and cost — most generation tasks complete under 2 seconds. Native SDK with structured JSON output reduces parsing errors. |
| Google Imagen 3 | imagen-3.0-generate-images-001 | AI logo generation — 4 logo variants per request based on industry, color, and font inputs. | Highest-quality image generation via Google AI Studio. Direct REST API, no third-party dependency. |
| Google PageSpeed | v5 API | Mobile and desktop performance scores (0–100) during SEO audit. | The authoritative performance score — what Google uses for rankings. Free API with generous limits. |
| Google Places | Places v1 | Local business discovery, ratings, location data for lead enrichment. | Most complete source of structured local business data available. |
Lead Generation & Outreach
| Service | Used For | Why |
|---|---|---|
| Oxylabs | Residential proxy network for scraping Google SERPs and directories without blocks. Max 5 concurrent sessions, 3 retries with backoff. | Residential IPs bypass anti-bot detection that blocks datacenter proxies. Realtime API returns fully rendered HTML — no headless browser needed for most pages. |
| Apollo.io | Contact enrichment — decision-maker names, emails, phone numbers from company domain. | Largest B2B contact database via API. Returns structured JSON with confidence scores. Often finds the exact owner/manager needed. |
| Instantly.ai | Production cold email sending — sequences, schedules, unsubscribe handling, delivery tracking via webhooks. | Specialized for cold outreach — handles warming, rotation across sending accounts, deliverability. Webhooks feed back into EmailEvent records. |
| Hunter.io | Domain-level email pattern discovery — finds most likely email format when Apollo has no direct contact. | Complements Apollo. Strong at inferring email patterns (first.last@company.com) when no direct contact exists. |
| Twilio | SMS outreach to carrier-verified mobile leads. | Carrier-verified mobiles convert better than cold email. Industry standard for programmable SMS with delivery receipts. |
Commerce & Infrastructure
| Service / Tool | Role | Why |
|---|---|---|
| Stripe | All payment processing — checkout sessions, subscriptions, billing portal, invoices, webhooks. | Standard for SaaS billing. Webhook-driven, no polling. Billing Portal lets clients self-manage without custom UI. |
| Hostinger API | Hosting slot management — sync available slots, track client assignments, query VM metrics. | BrandLift production infrastructure runs on Hostinger. API enables programmatic slot allocation. |
| PM2 | Process manager — keeps Next.js running, single fork mode on port 3001, 1GB memory ceiling, auto-restart. | ecosystem.config.js |
| Nginx | TLS termination, reverse proxy to :3001, serves static files from /public/ bypassing Node.js. | /etc/nginx/sites-available/brandlift-brain |
| Playwright | Contact form detection/submission during enrichment, template X-ray captures, screenshot generation. | More reliable than Puppeteer for modern SPAs. Stealth plugin bypasses bot detection on contact pages. |
| Remotion | Programmatic video rendering from React components. | Video creation with the same React/CSS skills already in the codebase. |
| Recharts | All data visualization — admin Command Center and Client Portal metrics. | Native React, composable, real DOM elements that respond to theme colors. |
| Sharp | Server-side image processing — resize, compress, convert uploaded assets. | Fastest Node.js image processing library. |
Section 04
The Five Pipelines
A. Lead Discovery
Step 1
Target Config
Industry + city
→
Step 2
SERP Scrape
Oxylabs geo-targeted
→
Step 3
Parse Results
Extract businesses
→
Step 4
LeadReservoir
Store + deduplicate
Key files: lib/oxylabs-client.ts, /api/pipeline/route.ts. Unique on domain_key (normalized domain).
B. Enrichment Pipeline
Step 1
Homepage Crawl
fetch + regex
→
Step 2
Apollo Lookup
people/domain search
→
Step 3
Hunter Fallback
Email pattern infer
→
Step 4
Contact Form
Playwright (if needed)
Key files: lib/enrichment/dom-crawler.ts, lib/apollo-engine.ts, lib/hunter-client.ts.
C. SEO Audit
| Category | Max Points | Example Signals |
|---|---|---|
| Technical | 25 | HTTPS, viewport meta, PageSpeed mobile/desktop |
| On-Page SEO | 25 | Title tag, meta description, H1, JSON-LD schema |
| Content | 20 | Services/About/Contact pages, word count, image alt text |
| Local SEO | 20 | Phone, address, Google Maps embed, review mentions |
| Trust | 10 | HTTPS, contact form, privacy/terms links |
Key file: lib/site-auditor.ts. Results cached in LeadReservoir.site_audit_json.
D. Proposal Dispatch
Step 1
Admin Release
One click in reservoir
→
Step 2
Create Proposal
Subdomain + DB record
→
Step 3
Gemini Copy
AI email generation
→
Step 4
Instantly Send
Campaign + tracking
Key files: lib/instantly-engine.ts, /api/leads/release. Auto-detects pathway: migrate (has website) or rebrand (new site).
E. Client Onboarding
Step 1
Proposal Accepted
Design + plan chosen
→
Step 2
Stripe Checkout
Plan selection
→
Step 3
Provision Account
ClientAccount + JWT
→
Step 4
Portal Access
Editor + hosting slot
Section 05
Database Schema
-- Lead-to-client chain
LeadReservoir ──(1:many)──→ Proposal ──(many:1)──→ ClientAccount
│
├──→ SiteTemplate
└──→ GeneratedLogo
-- Email tracking
LeadReservoir ──(1:many)──→ EmailEvent (ON DELETE CASCADE)
-- Hosting allocation
HostingPlan ──(1:many)──→ ServerSlot
| Model | Key Fields | Purpose |
|---|---|---|
| LeadReservoir | domain_key, enrichment_status, target_score, site_audit_json | Every discovered prospect. Unique on domain_key. |
| Proposal | subdomain, client_id, lead_id, custom_data | Released proposals. custom_data stores pathway + brand kit. |
| ClientAccount | email, active_plan, portal_access | Portal login credential. JWT signed from this row. |
| EmailEvent | event_type, apollo_message_id | Full email lifecycle: SENT → OPENED → CLICKED → REPLIED. |
| GeneratedLogo | image_url, is_selected | Imagen 3 outputs stored for reuse across proposal sessions. |
| ServerSlot | status (AVAILABLE/ACTIVE) | One slot = one hosted client website on Hostinger. |
Section 06
Infrastructure Layout
Brain Node (Primary)
Runs: Next.js 14, MySQL 8, Nginx, PM2 single fork on :3001
Static assets: Nginx serves /public/generated-logos/, /public/template-previews/, /public/videos/ directly from disk
Subdomains: Nginx wildcard *.brandlift.ai → all route to same Next.js app. Middleware rewrites {sub}.brandlift.ai → /portal/proposal/{sub}
Deploy Process
git pull npm run build # ~2 min Next.js production build pm2 restart brandlift-brain
Always run npm run build before restarting PM2. Restarting without a fresh build serves the previous compiled version. A corrupted build directory causes 500 errors on all API routes.
Section 07
Admin Tool Map
| URL | Name | Purpose |
|---|---|---|
/admin | Command Center | Home tile grid — entry point to all admin tools. KPIs, system event feed. |
/admin/leads | Lead Reservoir | Primary daily-use page. View, filter, release leads. Expandable rows show enrichment, email history, and actions. |
/admin/proposal-admin | Proposal Admin | All dispatched proposals — status, pathway, links to view or manage. |
/admin/proposal-preview | Proposal Preview | Side-by-side tabbed preview of both proposal templates (Web / No-Website). |
/admin/lead-engine | Lead Engine | Configure and trigger automated lead pipeline. Set target industry + city, run phases, monitor telemetry. |
/admin/hosting-slots | Hosting Slots | Visual grid of all Hostinger slots — AVAILABLE/ACTIVE/ERROR status. |
/admin/template-gallery | Template Gallery | Browse all template previews by industry. |
/admin/vault | Vault Manager | Full vault browser per category. Upload assets, set visibility/hero flags. |
/admin/media-library | Media Library | Browse and upload images across all industry categories. |
/admin/template-xray | Template X-Ray | Playwright-captured annotated screenshots. CSS calibration maps for brand injection. |
/admin/cms-white-label | CMS White Label | Configure WordPress admin branding — logos, CSS, footer text. |
/admin/crawling | OpenClaw Crawl | Manual crawl interface. URL + natural language extraction goal → structured data. |
/admin/openclaw | OpenClaw Probe | Deep AI-guided site intelligence extraction. |
/admin/settings | Global Settings | Pricing tier definitions and default email template subject/body. |
/admin/support-desk | Support Desk | Internal ticket console. View, comment, escalate to Hostinger. |
/admin/adam-config | ADAM Config | Knowledge base manager for the ADAM support AI. |
/admin/alert-config | Alert Config | Configure Slack/SMS alert routing by ticket type and priority. |
/admin/fleet-window | Fleet Window | Health monitor for Brain and Retina nodes. |
/admin/command-center | Command Center | Revenue charts, system events, client timeline, notification engine. |
/admin/site-builder | Site Builder | Headless GrapesJS editor for admins. Pick vault templates, inject brand data. |
Section 08
External Services & API Reference
| Service | Env Var(s) | Regenerate At | If It Goes Down |
|---|---|---|---|
| Google Gemini | GEMINI_API_KEY | aistudio.google.com | Taglines, copy, OpenClaw fail. Proposals still render. |
| Google Imagen 3 | GOOGLE_API_KEY | aistudio.google.com | Logo generation fails. Everything else unaffected. |
| Google PageSpeed | PAGE_SPEED_INSIGHTS_API_KEY | console.cloud.google.com | SEO audit runs without performance scores. |
| Oxylabs | OXYLABS_USERNAME/PASSWORD | dashboard.oxylabs.io | Lead discovery pipeline halts completely. |
| Apollo.io | APOLLO_API_KEY | apollo.io/settings | Contact enrichment fails. Hunter fallback still runs. |
| Instantly.ai | INSTANTLY_API_KEY, INSTANTLY_CAMPAIGN_ID | app.instantly.ai | Proposal emails not sent. Release action completes but email step fails. |
| Hunter.io | HUNTER_API_KEY | hunter.io/api-keys | Email fallback discovery fails. Low impact. |
| Twilio | TWILIO_ACCOUNT_SID/AUTH_TOKEN | console.twilio.com | SMS outreach fails. Email pipeline unaffected. |
| Stripe | STRIPE_SECRET_KEY, STRIPE_WEBHOOK_SECRET | dashboard.stripe.com | No new checkouts. Webhooks stop — client accounts not provisioned after payment. |
| Hostinger | HOSTINGER_API_TOKEN | hpanel.hostinger.com | Slot sync and VM metrics fail. Existing clients unaffected. |
Section 09
Scalability Roadmap
Current architecture is intentionally simple — a single server handles everything. Right for the current stage. Below is an honest assessment of limits and the scaling path.
Current Capacity
Comfortable at 50–200 active clients, 10,000+ leads, ~50 concurrent API requests before degradation. MySQL on localhost handles this range with <50ms median query time. PM2 single fork is a bottleneck under sustained Playwright/image-processing workloads.
NOW
Phase 0 — Single VPS
Next.js + MySQL + Nginx on one server. PM2 single fork. Two satellite nodes (Retina, Muscle) for template work.
~50–200 clients · ~10k leadsP1
Phase 1 — Managed Database
Move MySQL to PlanetScale/Railway/RDS. Decouples DB from app server, enables failover and read replicas. Prisma connection string is the only change needed.
~500 clients · ~100k leadsP2
Phase 2 — CDN for Generated Assets
Move /public/generated-logos/, /public/template-previews/ to Cloudflare R2 or S3. Reduces Brain node disk I/O and provides geographic caching.
~40% load reduction on BrainP3
Phase 3 — PM2 Cluster Mode
Enable 2–4 PM2 workers across CPU cores. Sessions are stateless JWT cookies so no coordination needed.
~2× throughput per coreP4
Phase 4 — Background Job Queue
Move Playwright tasks and Imagen/Gemini batch calls into BullMQ + Redis. Currently these block request handling synchronously.
Removes Playwright from request cycleP5
Phase 5 — Multi-Region Scraper Fleet
Expand from 1 Retina node to 3–5 dedicated scraper nodes in different US regions. Multiplies lead discovery throughput linearly.
500k+ leads/monthThe architecture is already designed for these transitions. Prisma abstracts the database, JWT sessions are stateless, and the satellite node pattern is proven. Phases 1–3 are incremental changes, not rewrites.
Section 10
Security Notes
| Layer | Mechanism | Cookie | Expiry |
|---|---|---|---|
| Admin access | Manual cookie set via /api/admin/set-admin-cookie. No password — admin access assumes trusted device. | bl_admin | Session |
| Client portal | Email + PBKDF2-SHA256 password. JWT signed with HMAC-SHA256 using PORTAL_JWT_SECRET. | bl_portal_session | 7 days |
| Admin emulation | Admin clicks "Client Portal" → emulate-client mints 2-hour JWT with emulated:true flag. | bl_portal_session | 2 hours |
HTTP-only Cookies
bl_portal_session cannot be read by JavaScript. XSS attacks cannot steal session tokens.
Stripe Webhook Verification
All Stripe payloads verified against STRIPE_WEBHOOK_SECRET before processing.
Proposal Pages Are Public
No auth required — they are sales pages intentionally accessible to prospects.
Admin Routes — No VPN Yet
/admin/* routes are not IP-restricted. VPN/IP allowlist planned for Phase 2 security hardening.
Support escalations involving billing, cancellations, or account access should be handled through /admin/support-desk — not by directly modifying the database.