EventPulse

Automated Post-Event Feedback Intelligence System

EventPulse is an intelligent feedback automation system built with OpenAI Agent Builder, ChatKit, and custom MCP servers. It automates survey delivery, collects responses, performs AI-powered analysis, and enables conversational queries for historical event data.

📚 Documentation

Complete documentation is in the eventpulse/ directory:

Getting Started

• eventpulse/README.md - Project overview and quick start

Technical Documentation

• eventpulse/TECHNICAL_SPEC.md - System architecture
• eventpulse/API_DOCUMENTATION.md - MCP Server API reference
• eventpulse/DATABASE_SCHEMA.md - Database design
• eventpulse/AGENT_BUILDER_GUIDE.md - Agent Builder configuration

Project Planning

• eventpulse/PRD.md - Product requirements
• eventpulse/MVP_IMPLEMENTATION_PLAN.md - MVP implementation plan

🚀 How to Start This Project

This project consists of two parts: the frontend (ChatKit) and the backend (MCP Server). Both need to be running.

Prerequisites

Before you begin, make sure you have:

• Node.js 18 or higher installed on your computer
• Python 3.8 or higher installed for the backend
• OpenAI API Key with access to Agent Builder
• Supabase account with database credentials
• Agent Builder workflow configured (refer to eventpulse/AGENT_BUILDER_GUIDE.md)

---

Part 1: Start the Backend MCP Server

The MCP Server handles database operations, AI analysis, and receives webhook calls from Google Forms.

Step 1: Install Backend Dependencies

Navigate to the MCP server directory and install Python dependencies:

cd mcp-server
python3 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
pip install -r requirements.txt

Step 2: Configure Backend Environment Variables

Create the backend environment file:

cp .env.example .env

Edit .env and add your credentials:

# OpenAI API Key (for AI analysis)
OPENAI_API_KEY=sk-proj-your-api-key

# Supabase Database
SUPABASE_URL=https://your-project.supabase.co
SUPABASE_KEY=your-supabase-service-role-key

# Server Authentication Token
MCP_SERVER_TOKEN=your-secure-token-here

Step 3: Start the Backend Server

Run the FastAPI server:

uvicorn app.main:app --reload

The backend will start on http://localhost:8000. You can verify it's running by visiting:

• Health check: http://localhost:8000/health
• API tools: http://localhost:8000/mcp/tools

Important: Keep this terminal running. The backend must be active to handle webhook calls from Google Forms and process feedback data.

---

Part 2: Start the Frontend (ChatKit)

Step 1: Install Frontend Dependencies

Open a new terminal (keep the backend running), navigate to the project root, and run:

cd /Users/liutonghao/Desktop/Ella_Project/ChatKit
npm install

This will install all required packages and dependencies for the frontend.

Step 2: Configure Frontend Environment Variables

Create a local environment configuration file:

cp .env.example .env.local

Then open .env.local and add your credentials:

# OpenAI API Key (get it from https://platform.openai.com/api-keys)
OPENAI_API_KEY=sk-proj-your-api-key

# ChatKit Workflow ID (from OpenAI Agent Builder)
NEXT_PUBLIC_CHATKIT_WORKFLOW_ID=wf_your-workflow-id

# EventPulse MCP Server URL (use localhost for local development)
NEXT_PUBLIC_MCP_SERVER_URL=http://localhost:8000

# MCP Server Bearer Token (must match the token in backend .env)
NEXT_PUBLIC_MCP_SERVER_TOKEN=your-secure-token-here

Step 3: Start the Frontend Development Server

Run the following command to start the application:

npm run dev

The frontend will start on http://localhost:3000. Open this URL in your web browser to access EventPulse.

Step 4: Test the Application

Try these example commands to verify everything is working:

• "Create a new customer event" - Creates an event with participants
• "Show all my events" - Displays all stored events
• "Analyze event with ID [event-id]" - Generates AI-powered feedback analysis
• "Get analysis for event [event-id]" - Retrieves previously stored analysis

---

Quick Summary

To run the full system locally, you need TWO terminals:

Terminal 1 - Backend:

cd mcp-server
source venv/bin/activate
uvicorn app.main:app --reload

Terminal 2 - Frontend:

npm run dev

Additional Commands

# Build frontend for production
npm run build

# Start frontend production server
npm start

# Run frontend code linter
npm run lint

🏗️ Architecture

┌─────────────────────────────────┐
│  ChatKit Frontend (This Repo)   │
│  - Next.js + React              │
│  - Conversational UI            │
│  - Client-side functions        │
└────────────┬────────────────────┘
             │
             ▼
┌─────────────────────────────────┐
│  Agent Builder Workflow         │
│  (OpenAI Platform)              │
│  - AI conversation routing      │
│  - Function calling             │
└────────────┬────────────────────┘
             │
             ▼
┌─────────────────────────────────┐
│  MCP Server (FastAPI)           │
│  - Event CRUD operations        │
│  - Feedback storage             │
│  - AI analysis                  │
│  - Database queries             │
└────────────┬────────────────────┘
             │
             ▼
┌─────────────────────────────────┐
│  Supabase (PostgreSQL)          │
│  - Event data                   │
│  - Feedback responses           │
│  - Analysis results             │
└─────────────────────────────────┘

Frontend Functions vs Backend MCP Tools

Frontend (This repository):

• Uses client-side functions to handle tool calls from Agent Builder
• Functions: store_event, get_events, analyze_event, get_analysis
• Location: components/ChatKitPanel.tsx (lines 288-354)
• Communication: Calls MCP Server REST API endpoints

Backend (Separate MCP Server repository):

• Uses MCP (Model Context Protocol) tools
• Exposes REST API endpoints at /mcp/tools/{function_name}
• Handles database operations and business logic
• See eventpulse/API_DOCUMENTATION.md for details

🛠️ Tech Stack

• Frontend: Next.js 15, React 19, TypeScript, Tailwind CSS
• UI Component: @openai/chatkit-react
• Agent Platform: OpenAI Agent Builder
• Backend: FastAPI (Python) MCP Server (separate repository)
• Database: Supabase (PostgreSQL)
• Automation: Zapier (optional)

📁 Project Structure

ChatKit/
├── app/                    # Next.js App Router
│   ├── api/
│   │   └── create-session/ # ChatKit session endpoint
│   ├── App.tsx             # Main application component
│   ├── layout.tsx          # Root layout
│   └── page.tsx            # Home page
├── components/             # React components
│   ├── ChatKitPanel.tsx    # Main ChatKit integration
│   └── ErrorOverlay.tsx    # Error handling UI
├── lib/
│   └── config.ts           # App configuration (prompts, theme, greeting)
├── hooks/
│   └── useColorScheme.ts   # Theme management
├── eventpulse/             # 📚 Complete documentation
│   ├── README.md           # Project overview
│   ├── PRD.md              # Product requirements
│   ├── TECHNICAL_SPEC.md   # Technical architecture
│   ├── AGENT_BUILDER_GUIDE.md  # Agent Builder setup
│   ├── API_DOCUMENTATION.md    # MCP Server API
│   ├── DATABASE_SCHEMA.md      # Database design
│   └── MVP_IMPLEMENTATION_PLAN.md
├── DOCUMENTATION.md        # 📖 Documentation index
└── .env.local              # Environment variables (create from .env.example)

🧪 Testing

# Test 1: Create Event
User: "Create a new event called 'Team Workshop' on March 20th"
Expected: Event created confirmation

# Test 2: View Events
User: "Show all my events"
Expected: List of all events

# Test 3: Analyze Feedback
User: "Analyze event with ID [event-id]"
Expected: AI-generated analysis with sentiment, themes, suggestions

📖 Learn More

• EventPulse Documentation
• ChatKit JavaScript Library
• OpenAI Agent Builder

🔧 Development

# Development mode
npm run dev

# Production build
npm run build

# Start production server
npm start

# Lint code
npm run lint

🚀 Deployment

Before deploying:

1. Set up production environment variables
2. Configure domain in OpenAI Domain Allowlist
3. Deploy MCP Server (see API documentation)
4. Test all functions in production

📄 License

Internal Use Only - Aetheron

---

Need Help? See eventpulse/README.md for complete guides and troubleshooting.