BrandLift.ai
Application Blueprint

Network Topology

# DNS: brandlift.ai → 84.x.x.x (Brain VPS)
# DNS: *.brandlift.ai → same IP (wildcard A record)

Internet
  └─ Nginx (port 443 + 80 → 443 redirect)
       ├─ Wildcard TLS cert (Let's Encrypt, auto-renew certbot)
       ├─ /public/* served from /var/www/BrandLift/public/ (bypasses Node)
       └─ All other traffic → proxy_pass http://localhost:3001

localhost:3001
  └─ Next.js 14 (PM2, single fork, process name: brandlift-brain)
       ├─ next/server middleware (runs on every request before routing)
       ├─ /app/api/** — all server API routes
       ├─ /app/admin/** — admin pages (server components, require bl_admin cookie)
       ├─ /app/portal/** — client portal (layout checks JWT)
       └─ /app/domain-checker — public page

localhost:3306
  └─ MySQL 8.0 (user: brandlift, db: brandlift)

Remote: 187.124.243.5 (Retina)
  ├─ Template vault (rsync + direct HTTP fetch)
  ├─ Ghost CMS (blog layer, unused in current flow)
  └─ Playwright scraper relay scripts

Remote: 187.124.95.147 (Muscle)
  ├─ WordPress showroom instances
  └─ Golden master deployments for client sites

Subdomain Routing

Middleware intercepts requests where hostname !== brandlift.ai and rewrites the path to /portal/proposal/{subdomain}. The x-pathname header is set on all responses so server-side layouts can distinguish proposal pages from portal pages without accessing cookies.

Repository Structure

/var/www/BrandLift/
├── app/                          # Next.js App Router root
│   ├── admin/                    # 20 admin pages (server components)
│   ├── api/                      # 120+ API route handlers
│   ├── portal/                   # Client portal pages
│   │   ├── layout.tsx            # Portal layout — checks auth, strips chrome on proposals
│   │   ├── PortalShell.tsx       # Client component — sidebar/header (skipped for proposals)
│   │   ├── dashboard/            # /portal/dashboard
│   │   ├── proposal/[subdomain]/ # /portal/proposal/[sub] — public proposal page
│   │   └── billing/              # /portal/billing
│   ├── domain-checker/           # Public domain search page
│   ├── editor/[siteId]/          # GrapesJS site editor
│   ├── layout.tsx                # Root layout
│   └── globals.css
├── components/                   # Shared React components
│   ├── proposal/
│   │   ├── ForensicProposalClient.tsx  # Main proposal page (~1600 lines)
│   │   └── ...
│   └── ui/
├── lib/                          # Server-side utilities (never imported by client components)
│   ├── ai-foundry.ts             # Gemini + Imagen wrapper
│   ├── apollo-engine.ts          # Apollo.io API client
│   ├── brand-kit/                # Brand PDF, favicon, metadata generators
│   ├── enrichment/dom-crawler.ts # HTML→structured data extractor
│   ├── garbage-collector.ts      # Cleanup utility for temp assets
│   ├── hunter-client.ts          # Hunter.io email pattern API
│   ├── instantly-engine.ts       # Instantly.ai campaign engine
│   ├── notifications/            # Slack + internal notify
│   ├── oxylabs-client.ts         # Residential proxy scraper
│   ├── portal/auth.ts            # JWT sign/verify, session helpers
│   ├── portal/require-auth.ts    # Auth guard for portal server components
│   ├── prisma.ts                 # Singleton PrismaClient
│   ├── services/provision.ts     # Client account + hosting provisioning
│   ├── site-auditor.ts           # 20-signal SEO audit runner
│   ├── storage.ts                # Local file storage helpers
│   ├── teardown-lead.ts          # Lead cleanup on drop/cancel
│   └── twilio-sms.ts             # Twilio SMS client
├── prisma/
│   ├── schema.prisma             # Authoritative DB schema
│   └── migrations/               # Prisma migration history
├── public/                       # Static assets (Nginx-served)
│   ├── generated-logos/          # Imagen 3 outputs
│   ├── template-previews/        # Industry template screenshots
│   ├── videos/                   # Proposal cinematic videos
│   └── *.html                    # Internal docs (tech-overview, pitch, etc.)
├── middleware.ts                 # Next.js edge middleware
├── ecosystem.config.js           # PM2 config
├── next.config.mjs               # Next.js config (image domains, etc.)
├── .env                          # 50+ environment variables (NOT committed)
└── package.json

Middleware Layer

File: middleware.ts. Runs on the Next.js Edge Runtime before every request. Two responsibilities:

Authentication Model

JWT Payload Shape

{
  email:        string,          // client email or "preview-{leadId}@brandlift.ai"
  company_name: string,          // from ClientAccount or lead data
  active_plan:  string,          // "Launch" | "Growth" | "Authority"
  emulated?:    boolean,         // present on admin emulation sessions
  admin_origin?:boolean,         // came from /api/admin/emulate-client
  preview?:     boolean,         // no real ClientAccount exists
  iat:          number,          // issued at (unix)
  exp:          number           // expiry (unix)
}

Database Schema

32 Prisma models. MySQL 8. Key relationships below.

-- Primary lead-to-client chain
LeadReservoir (1) ──── (many) Proposal
Proposal      (many) ──── (1) ClientAccount    [optional — null until payment]
ClientAccount (1) ──── (many) ClientSite
ClientSite    (many) ──── (1) SiteTemplate

-- Email tracking
LeadReservoir (1) ──── (many) EmailEvent       [ON DELETE CASCADE]

-- Hosting infrastructure
HostingPlan   (1) ──── (many) ServerSlot       [status: AVAILABLE | ACTIVE | ERROR]

-- Brand assets
Proposal      (1) ──── (many) GeneratedLogo    [Imagen 3 outputs for a lead]

-- Support system
SupportTicket (1) ──── (many) TicketComment
SupportTicket (many) ──── (1) HostingerEscalation [optional]

-- AI knowledge base
AdamKnowledge (standalone) — FAQ articles for ADAM AI
AdamQA        (standalone) — Q&A pairs for ADAM training

-- Web crawling
WebCrawlerJob (standalone) — OpenClaw crawl tasks + results JSON

Prisma Configuration

# prisma/schema.prisma
datasource db {
  provider = "mysql"
  url      = env("DATABASE_URL")
}

generator client {
  provider = "prisma-client-js"
}

DATABASE_URL format: mysql://brandlift:password@localhost:3306/brandlift?connection_limit=10

Singleton client in lib/prisma.ts prevents connection pool exhaustion in development hot-reload cycles:

const globalForPrisma = globalThis as unknown as { prisma: PrismaClient };
export const prisma = globalForPrisma.prisma ?? new PrismaClient();
if (process.env.NODE_ENV !== 'production') globalForPrisma.prisma = prisma;

Admin API Routes

All admin routes check for bl_admin cookie. Return 401 if missing/invalid.

Brand & AI API Routes

Portal API Routes

Inbound Webhook Routes

Public / Lead Pipeline Routes

Core Library Files

External Dependencies & Environment Variables

Deployment Procedures

Standard Deploy

cd /var/www/BrandLift
git pull origin main
npm install              # if package.json changed
npx prisma migrate deploy  # if schema changed
npm run build            # ~2 min
pm2 restart brandlift-brain
pm2 logs brandlift-brain --lines 50  # verify clean start

PM2 Configuration (ecosystem.config.js)

module.exports = {
  apps: [{
    name: 'brandlift-brain',
    script: 'node_modules/.bin/next',
    args: 'start',
    cwd: '/var/www/BrandLift',
    env: { PORT: 3001, NODE_ENV: 'production' },
    max_memory_restart: '1G',
    instances: 1,          // single fork — not cluster
    autorestart: true,
    watch: false,
  }]
}

Nginx Config Summary

# /etc/nginx/sites-available/brandlift-brain
server {
  listen 443 ssl;
  server_name brandlift.ai *.brandlift.ai;
  ssl_certificate     /etc/letsencrypt/live/brandlift.ai/fullchain.pem;
  ssl_certificate_key /etc/letsencrypt/live/brandlift.ai/privkey.pem;

  # Static assets bypass Node.js
  location /generated-logos/ { alias /var/www/BrandLift/public/generated-logos/; }
  location /template-previews/ { alias /var/www/BrandLift/public/template-previews/; }

  location / {
    proxy_pass http://localhost:3001;
    proxy_set_header Host $host;         # CRITICAL: preserves subdomain for middleware
    proxy_set_header X-Real-IP $remote_addr;
  }
}

Known Risks

Technical Debt Register