AI-Powered ICP Generator & Outreach Platform

An intelligent B2B sales platform that generates Ideal Customer Profiles (ICPs) using AI, finds prospects, and automates personalized outreach via email and AI-powered phone calls.

🚀 Features

• AI-Powered ICP Generation: Generate comprehensive Ideal Customer Profiles based on your target market using GPT-5 and web research
• Smart Prospect Research: Automatically find and enrich prospects that match your ICPs
• Personalized Email Outreach: Generate contextual, personalized sales emails with AI
• AI Voice Calls: Initiate AI-powered sales calls using Vapi
• Real-time Collaboration: Chat with AI to refine your ICPs interactively
• Outreach History Tracking: Keep track of all interactions with prospects
• Full Telemetry: Monitor AI performance with Opik integration

🛠 Tech Stack

• Frontend: Next.js 15 (App Router), React 19, TypeScript, Tailwind CSS
• Backend: Convex (real-time database)
• AI: OpenAI GPT-5 (via Vercel AI SDK)
• Search: Exa API
• Authentication: Auth0
• Email: Resend
• Voice AI: Vapi
• Telemetry: Opik + OpenTelemetry
• UI Components: Radix UI, Lucide Icons, Framer Motion

📋 Prerequisites

Before you begin, ensure you have the following installed:

• Node.js 20.x or higher
• pnpm (recommended) or npm
• Git

You'll also need accounts and API keys for:

• OpenAI - For AI-powered ICP generation and email writing
• Convex - For real-time database
• Auth0 - For user authentication
• Exa - For web search capabilities
• Resend - For email delivery
• Vapi - For AI voice calls (optional)
• Opik - For AI observability (optional)

🔧 Installation

1. Clone the repository

git clone <your-repo-url>
cd ai-by-the-bay

2. Install dependencies

pnpm install
# or
npm install

3. Set up Convex

# Install Convex CLI globally
pnpm add -g convex

# Login to Convex
npx convex login

# Initialize Convex project
npx convex dev

This will create a .env.local file with your Convex deployment URL.

4. Configure environment variables

Copy the example environment file:

cp .env.example .env.local

Edit .env.local and add your API keys:

# OpenAI API Key (Required)
OPENAI_API_KEY=sk-...

# Exa API Key (Required - for search)
EXA_API_KEY=...

# Auth0 Configuration (Required)
AUTH0_SECRET=use_openssl_rand_hex_32_to_generate_this
AUTH0_BASE_URL=http://localhost:3000
AUTH0_ISSUER_BASE_URL=https://your-tenant.auth0.com
AUTH0_CLIENT_ID=...
AUTH0_CLIENT_SECRET=...

# App Configuration
APP_BASE_URL=http://localhost:3000

# Convex (Auto-generated by `npx convex dev`)
CONVEX_DEPLOYMENT=...
NEXT_PUBLIC_CONVEX_URL=https://...

# Resend (Required for email outreach)
RESEND_API_KEY=re_...

# Vapi (Optional - for AI voice calls)
VAPI_API_KEY=...
VAPI_ASSISTANT_ID=...

# Opik Telemetry (Optional - for AI observability)
OPIK_API_KEY=...
OPIK_WORKSPACE=...
OPIK_URL_OVERRIDE=https://www.comet.com/opik/api

5. Generate AUTH0_SECRET

openssl rand -hex 32

🚀 Running the Project

Development Mode

1. Start Convex backend (in one terminal):

npx convex dev

2. Start Next.js development server (in another terminal):

pnpm dev
# or
npm run dev

3. Open your browser

Navigate to http://localhost:3000

Production Build

# Build the project
pnpm build

# Start production server
pnpm start

📁 Project Structure

ai-by-the-bay/
├── app/                          # Next.js App Router
│   ├── (main)/                   # Main application routes
│   │   ├── icps/                 # ICP management pages
│   │   └── me/                   # User profile
│   ├── api/                      # API routes
│   │   ├── chat-icp/             # ICP refinement chat
│   │   ├── generate-icps/        # ICP generation
│   │   ├── outreach/             # Email & call APIs
│   │   └── prospect/             # Prospect research
│   └── layout.tsx                # Root layout with Auth0
├── components/                   # React components
│   ├── ui/                       # Reusable UI components
│   ├── ChatPanel.tsx             # ICP chat interface
│   ├── EmailComposer.tsx         # Email composition
│   └── CallInterface.tsx         # Voice call interface
├── convex/                       # Convex backend
│   ├── icps.ts                   # ICP database operations
│   ├── prospecting.ts            # Prospect research
│   ├── outreach.ts               # Outreach campaigns
│   └── schema.ts                 # Database schema
├── lib/                          # Utilities and schemas
│   └── schemas/                  # Zod schemas
├── guides/                       # Documentation
│   └── llm-calls-with-telemetry.md
└── instrumentation.ts            # OpenTelemetry setup

🎯 Key Features Guide

1. Generate ICPs

1. Navigate to the home page
2. Enter your target customer description (e.g., "SaaS companies that need better analytics")
3. Optionally, describe what you're building
4. Click "Generate ICPs"
5. The system will:
   • Generate search queries
   • Research the market using Exa
   • Create 3 detailed ICPs using GPT-5

2. Refine ICPs with AI Chat

• Click on any ICP to view details
• Use the chat panel to refine specific sections
• AI will suggest improvements and update the ICP in real-time

3. Find Prospects

1. Select an ICP
2. Click "Research Prospects"
3. The system finds companies and decision-makers matching your ICP
4. View enriched prospect data including contact information

4. Send Personalized Outreach

Email Outreach:

1. Select a prospect
2. Click "Email"
3. AI generates a personalized email based on ICP messaging
4. Review, edit, and send

AI Voice Calls:

1. Select a prospect
2. Click "Call"
3. AI initiates a call using Vapi with context about the prospect
4. Track call outcomes

📊 Telemetry & Monitoring

All AI calls are instrumented with OpenTelemetry and sent to Opik for observability:

• View token usage and costs
• Track response times
• Monitor AI quality
• Debug issues

See guides/llm-calls-with-telemetry.md for implementation details.

🔑 Environment Variables Reference

Variable	Required	Description
OPENAI_API_KEY	✅	OpenAI API key for GPT-5
EXA_API_KEY	✅	Exa API key for web search
AUTH0_SECRET	✅	Random secret for Auth0 session encryption
AUTH0_BASE_URL	✅	Your app URL (http://localhost:3000 for dev)
AUTH0_ISSUER_BASE_URL	✅	Your Auth0 tenant URL
AUTH0_CLIENT_ID	✅	Auth0 application client ID
AUTH0_CLIENT_SECRET	✅	Auth0 application client secret
CONVEX_DEPLOYMENT	✅	Convex deployment ID (auto-generated)
NEXT_PUBLIC_CONVEX_URL	✅	Convex API URL (auto-generated)
RESEND_API_KEY	✅	Resend API key for email delivery
VAPI_API_KEY	⚠️	Vapi API key (optional, for voice calls)
VAPI_ASSISTANT_ID	⚠️	Vapi assistant ID (optional)
OPIK_API_KEY	⚠️	Opik API key (optional, for telemetry)
OPIK_WORKSPACE	⚠️	Opik workspace name (optional)

🐛 Troubleshooting

Convex Connection Issues

# Clear Convex cache and restart
rm -rf .convex
npx convex dev

Auth0 Login Redirect Loop

• Ensure AUTH0_BASE_URL matches your actual URL
• Check that Auth0 callback URLs are configured correctly in Auth0 dashboard
• Verify AUTH0_SECRET is set and is a valid 32-byte hex string

Build Errors

# Clean install dependencies
rm -rf node_modules pnpm-lock.yaml
pnpm install

# Clear Next.js cache
rm -rf .next
pnpm build

API Rate Limits

• OpenAI: Monitor usage at https://platform.openai.com/usage
• Exa: Check rate limits in your Exa dashboard
• Consider adding rate limiting middleware for production

📝 Development Guidelines

Making LLM Calls

All LLM calls should:

• Be made from Next.js API routes (not Convex)
• Include experimental_telemetry: { isEnabled: true }
• Use proper error handling

See guides/llm-calls-with-telemetry.md for the complete guide.

Database Schema Changes

When modifying Convex schema:

# Push schema changes
npx convex dev

# Clear data (if needed)
npx convex run clearAll

🚢 Deployment

Vercel (Recommended)

1. Push your code to GitHub
2. Import project to Vercel
3. Add all environment variables
4. Deploy!

Vercel will automatically:

• Build with Turbopack
• Connect to Convex
• Set up preview deployments

Environment Variables for Production

Remember to update:

• AUTH0_BASE_URL → your production URL
• APP_BASE_URL → your production URL
• All other API keys should use production credentials

📚 Additional Resources

• Next.js Documentation
• Convex Documentation
• Vercel AI SDK
• Auth0 Next.js SDK
• Opik Documentation

🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Run tests: pnpm build
5. Submit a pull request

🙏 Acknowledgments

Built with:

• OpenAI GPT-5
• Convex real-time database
• Vercel AI SDK
• And many other amazing open-source projects

---

Need help? Check out the guides/ directory for detailed documentation on specific features.