# Project export: Segmind This document was generated by HackStack to give an AI agent context about a hackathon project. Sections are labeled with their provenance; content marked as truncated was cut to keep this document small. ## Project metadata - Hackathon: Cal Hacks 12.0 - Tagline: Reimagining market engagement through AI. - Devpost: https://devpost.com/software/segmind - GitHub: https://github.com/PatrickGaied/Twilio - Video: https://www.youtube.com/embed/-6UbbbmzcHU?enablejsapi=1&hl=en_US&rel=0&start=&version=3&wmode=transparent - Team: 4 GitHub contributor(s) — BakedSoups (19 commits), Patrick Gaied (17 commits), James Burrell (1 commits), Eric Taylor (1 commits) ## Devpost submission (written by the team) ### Inspiration We saw Segment, a past YC company, and thought, what if we took that idea further? Segmind reimagines customer analytics with AI, turning fragmented data into real-time insights and automatically generated campaigns. ### What it does Segmind analyzes customer behavior, segments audiences with AI, and auto-generates personalized campaigns that actually convert. It’s like ChatGPT for your marketing data. ### How we built it We used FastAPI, React, and PostgreSQL with GPT-powered insight generation and clustering models built on Scikit-learn. The result is a real-time, full-stack marketing intelligence platform. ### Challenges we ran into Balancing automation with interpretability was tough, we wanted the AI to feel smart and transparent. Integrating live insights without overwhelming users was another key design challenge. ### Accomplishments we're proud of We built a production-ready AI dashboard in under 48 hours that generates real campaigns and visualizes segment behavior live. The UX feels like something a real startup could ship. ### What we learned Great AI tools aren’t just about accuracy, they’re about clarity, trust, and speed. We learned how to merge data science with great design. ### What's next We’re improving our customer analytics engine to capture deeper behavioral patterns and lifetime value predictions. Next, we’ll finish training custom ad-generation models to create hyper-personalized, conversion-optimized campaigns at scale. ## README (from the GitHub repository) # Segmind MVP - Customer Messaging Platform A modern customer messaging and segmentation platform with multi-channel support (SMS, Email, WhatsApp, Push). ## Quick Start - Two Ways to Run ### Option 1: Using Docker (Recommended - No Setup Required!) #### Requirements - Docker Desktop installed ([Download here](https://docker.com)) #### Run with Docker **Windows:** ```cmd start-docker.bat ``` **Mac/Linux:** ```bash ./start-docker.sh ``` That's it! Docker handles everything: - ✅ No Python version issues - ✅ No Node.js version issues - ✅ No venv problems - ✅ No dependency conflicts - ✅ Works the same on every machine Visit http://localhost:3000 after containers start. ### Option 2: Run Locally with Python #### Requirements - Python 3.7+ installed - Node.js 14+ installed #### Run Locally ```bash python run.py ``` Then choose option 2. **Note:** If you're having issues with the Python script (infinite loops, venv problems), use Docker instead! ## Why Docker is Better With Docker: - **Zero Setup**: Just install Docker and run - **No Python/Node Version Conflicts**: Container has the right versions - **No Venv Issues**: Everything runs in isolated containers - **Cross-Platform**: Same command works on Windows, Mac, Linux - **Clean System**: Nothing installed on your machine - **Easy Cleanup**: Just stop containers and delete them ## Docker Commands **Start the app:** ```bash docker-compose up ``` **Stop the app:** ```bash docker-compose down ``` **Rebuild after code changes:** ```bash docker-compose up --build ``` **View logs:** ```bash docker-compose logs backend docker-compose logs frontend ``` **Clean everything:** ```bash docker-compose down -v --remove-orphans ``` ## URLs Once running, access: - **Frontend Dashboard**: http://localhost:3000 - **Backend API**: http://localhost:8000 - **API Documentation**: http://localhost:8000/docs ## Features - 📊 Real-time customer segmentation - 📨 Multi-channel messaging (SMS, Email, WhatsApp, Push) - 📈 Analytics and ROI tracking - 🎯 Targeted campaign management - 🔄 Real-time metrics dashboard - 🚀 Fast, modern tech stack (FastAPI + Next.js) - 📧 Email generation from analytics ## Customer Segments The platform tracks 5 key customer segments: - **High Converters** (6.5%) - Premium customers with high conversion rates - **Window Shoppers** (35.4%) - High browse rate, low purchase rate - **Cart Abandoners** (20.3%) - Started checkout but didn't complete - **Loyal Customers** (9.7%) - Repeat purchasers - **At Risk** (28.1%) - Haven't engaged recently ## Project Structure ``` . ├── segmind/ │ ├── backend/ │ │ ├── main.py # FastAPI entrypoint │ │ ├── requirements.txt # Backend dependencies │ │ ├── routes/ │ │ │ ├── analytics.py # Analytics endpoints │ │ │ └── segments.py # Customer segments endpoints │ │ └── tests/ # Backend tests │ └── frontend/ # Next.js frontend application ├── docker-compose.yml # Docker orchestration ├── Dockerfile.backend # Backend container config ├── Dockerfile.frontend # Frontend container config ├── start-docker.sh # Unix Docker starter ├── start-docker.bat # Windows Docker starter └── .env # Environment configuration ``` ## Troubleshooting ### Docker Issues 1. Make sure Docker Desktop is running 2. Check ports 3000 and 8000 are free 3. Try `docker-compose down` then `docker-compose up --build` ### Local Python Issues 1. If venv loops infinitely → Use Docker instead 2. If dependencies fail → Use Docker instead 3. If versions conflict → Use Docker instead ## Key Metrics Displayed - **Total Messages**: 156,789 messages sent - **Total Customers**: 44,054 tracked customers - **Revenue Attributed**: $2,847,593.45 - **Engagement Rate**: 24.7% average - **Channel Performance**: ROI by channel (SMS, Email, WhatsApp, Push) ## Development The app auto-reloads on code changes: - Backend: Edit `backend_api.py` and it auto-reloads - Frontend: Edit files in `segmind/frontend/` and it auto-reloads No need to restart containers!# Contribution test - PatrickGaied ## Detected evidence (automated analysis) Indexed codebase: 92 recognized source files, 1153 KB. - CSS (language) — detected in the code - FastAPI (technology) — detected in the code - JavaScript (language) — detected in the code - Next.js (technology) — detected in the code - Python (language) — detected in the code - React (technology) — detected in the code - Redis (technology) — detected in the code - Supabase (technology) — detected in the code - Tailwind CSS (technology) — detected in the code - TypeScript (language) — detected in the code - C++ (language) — claimed on Devpost, not found in the code ## Codebase structure (from repository index) ### Files (119 of 119) ``` .env.example .gitignore campaign_result.json chroma.py docker-compose.yml Dockerfile.backend Dockerfile.frontend ecommerce_pattern_analysis.ipynb generate_campaign_cards.py INTEGRATION_GUIDE.md kaggle_tools/.gitignore kaggle_tools/customer_insights_for_messaging.py kaggle_tools/load_ecommerce_to_sqlite.py kaggle_tools/query_supabase.py kaggle_tools/README.md kaggle_tools/upload_sample_to_supabase.py local_campaign_generator.py product_segment_api.py query_supabase.py README.md requirements.txt segmind/backend/.gitignore segmind/backend/api_usage_example.md segmind/backend/audience_insights.py segmind/backend/core/utils/config.py segmind/backend/core/utils/schemas.py segmind/backend/example.env segmind/backend/generate_campaign_cards.py segmind/backend/main.py segmind/backend/requirements.txt segmind/backend/routes/__init__.py segmind/backend/routes/analytics.py segmind/backend/routes/campaign_generator.py segmind/backend/routes/campaigns.py segmind/backend/routes/insights.py segmind/backend/routes/messaging.py segmind/backend/routes/popup_generator.py segmind/backend/routes/products.py segmind/backend/routes/segments.py segmind/backend/routes/templates.py segmind/docker-compose.yml segmind/frontend/.env.example segmind/frontend/.gitignore segmind/frontend/all_campaigns_combined.json segmind/frontend/campaign_cards_output.json segmind/frontend/campaign_generator_optimized.py segmind/frontend/campaigns_iphone_15_pro.json segmind/frontend/campaigns_macbook_pro.json segmind/frontend/campaigns_samsung_galaxy_s24.json segmind/frontend/components/AIChat.tsx segmind/frontend/components/AudienceChat.tsx segmind/frontend/components/CalendarCampaignBuilder.tsx segmind/frontend/components/CalendarCampaignBuilderSimple.tsx segmind/frontend/components/CampaignCalendar.tsx segmind/frontend/components/CampaignCalendarModal.tsx segmind/frontend/components/CampaignGenerationModal.tsx segmind/frontend/components/CampaignModal.tsx segmind/frontend/components/CampaignTypeSelection.tsx segmind/frontend/components/DashboardCharts.tsx segmind/frontend/components/DataAnalysisPrompt.tsx segmind/frontend/components/EmailTemplates.tsx segmind/frontend/components/ImageGenerator.tsx segmind/frontend/components/InsightAnalysis.tsx segmind/frontend/components/PopupAdCreator.tsx segmind/frontend/components/PopupAdGeneratorModal.tsx segmind/frontend/components/PopupCampaignBuilder.tsx segmind/frontend/components/ProductSegmentInsights.tsx segmind/frontend/components/QuickInsightAnalysis.tsx segmind/frontend/components/ThemeToggle.tsx segmind/frontend/contexts/ThemeContext.tsx segmind/frontend/Dockerfile segmind/frontend/example_usage.py segmind/frontend/generate_campaign_cards.py segmind/frontend/next.config.js segmind/frontend/package.json segmind/frontend/pages/_app.tsx segmind/frontend/pages/_document.tsx segmind/frontend/pages/analytics.tsx segmind/frontend/pages/api/audience-insights.ts segmind/frontend/pages/api/chat.ts segmind/frontend/pages/api/generate-campaign-cards.ts segmind/frontend/pages/api/generate-campaigns-custom.ts segmind/frontend/pages/api/generate-campaigns.ts segmind/frontend/pages/api/generate-email-image.ts segmind/frontend/pages/api/generate-email.ts segmind/frontend/pages/api/generate-image.ts segmind/frontend/pages/api/generate-popup-ads.ts segmind/frontend/pages/api/generate-popup-content.ts segmind/frontend/pages/breakdown.tsx segmind/frontend/pages/campaign/create.tsx segmind/frontend/pages/campaigns.tsx segmind/frontend/pages/index.tsx segmind/frontend/pages/insights/[product].tsx segmind/frontend/pages/popup-preview.tsx segmind/frontend/pages/products.tsx segmind/frontend/pages/segments-backup.tsx segmind/frontend/pages/segments-new.tsx segmind/frontend/pages/segments-test.tsx segmind/frontend/pages/segments.tsx segmind/frontend/pages/segments.tsx.broken segmind/frontend/postcss.config.js segmind/frontend/README_python.md segmind/frontend/requirements.txt segmind/frontend/scripts/theme-script.js segmind/frontend/styles/globals.css segmind/frontend/tailwind.config.js segmind/frontend/test_api_debug.js segmind/frontend/test_api.js segmind/frontend/tsconfig.json segmind/OCR.ipynb segmind/README.md segmind/requirements.txt segmind/run.sh segmind/scripts/seed_demo.py segmind/sdk/js/segmind.js start-docker.bat start-docker.sh test_campaign_generation.sh test_payload.json ``` ### Dependencies - requirements.txt: chromadb@==0.4.22, google-generativeai, pandas@==2.1.4, pillow, python-dotenv, requests@==2.31.0 - segmind/backend/requirements.txt: chromadb@==0.4.24, fastapi@==0.115.6, google-genai@==1.46.0, numpy@==1.26.4, pillow@==10.1.0, python-dotenv@==1.0.0, python-multipart@==0.0.6, requests@==2.31.0, supabase@==2.12.0, uvicorn[standard]@==0.32.1 - segmind/frontend/package.json: @radix-ui/react-dialog@^1.0.5, @radix-ui/react-select@^2.0.0, @radix-ui/react-tabs@^1.0.4, @types/node@^20.8.0, @types/react@^18.2.25, @types/react-dom@^18.2.11, autoprefixer@^10.4.16, axios@^1.5.0, class-variance-authority@^0.7.0, clsx@^2.0.0, eslint@^8.52.0, eslint-config-next@14.0.0, lucide-react@^0.292.0, next@14.0.0, postcss@^8.4.31, react@^18.2.0, react-dom@^18.2.0, recharts@^2.8.0, tailwind-merge@^2.0.0, tailwindcss@^3.3.5, typescript@^5.2.2 - segmind/frontend/requirements.txt: requests@>=2.31.0 - segmind/requirements.txt: celery@==5.3.4, fastapi@==0.104.1, httpx@==0.25.2, jinja2@==3.1.2, numpy@==1.24.3, pandas@==2.1.4, passlib[bcrypt]@==1.7.4, psycopg2-binary@==2.9.9, pydantic@==2.5.1, python-dotenv@==1.0.0, python-jose[cryptography]@==3.3.0, python-multipart@==0.0.6, redis@==5.0.1, requests@==2.31.0, sqlalchemy@==2.0.23, uvicorn[standard]@==0.24.0 ### Recent commits (newest first) - Merge branch 'main' - test - Merge branch 'main' of https://github.com/PatrickGaied/Twilio - Image gen - test - working - done sleep now yes - refactor: smoother loading email funcitality in email - feat: added option to swithc between popup or calender ads, improved routing on camapaign generator - refactor: segment prototyping - campaign strategy implementaiton - feat: calender creation template - refactor:create campaign styling - refactor: chat log intergrated - modernized UI implemented basic popup generation - Merge branch 'main' of https://github.com/PatrickGaied/Twilio - refactor: implemented ui changes - refactor: segments tab fixed - Merge branch 'main' of https://github.com/PatrickGaied/Twilio - refactor: better loading state ## Key source files (fetched from GitHub, selected and truncated for size) ### INTEGRATION_GUIDE.md ```markdown # ChromaDB and OCR Integration Guide This guide explains how to integrate ChromaDB vector database and OCR capabilities with the Twilio marketing platform for enhanced product recommendations and campaign analysis. ## Overview The platform currently uses mock data but is designed to integrate with: - **ChromaDB**: Vector database for product similarity and recommendations - **OCR Processing**: Image analysis for campaign content optimization - **OpenAI**: AI-powered content generation ## ChromaDB Integration ### 1. Setup ChromaDB ```bash # Install ChromaDB pip install chromadb # For persistent storage pip install chromadb[persistent] ``` ### 2. Product Vector Storage ```python import chromadb from chromadb.config import Settings # Initialize ChromaDB client client = chromadb.Client(Settings( chroma_db_impl="duckdb+parquet", persist_directory="./chroma_db" )) # Create collection for products products_collection = client.create_collection( name="products", metadata={"description": "Product embeddings for similarity search"} ) # Example: Add product vectors product_data = [ { "id": "iphone_15_pro", "name": "iPhone 15 Pro", "category": "smartphone", "price": 999, "features": ["A17 Pro chip", "Pro camera system", "Titanium"], "description": "Professional smartphone with advanced camera and performance" }, # ... more products ] # Generate embeddings and add to ChromaDB for product in product_data: # Use OpenAI or other embedding model embedding = generate_embedding(product["description"] + " " + " ".join(product["features"])) products_collection.add( embeddings=[embedding], documents=[product["description"]], metadatas=[{ "name": product["name"], "category": product["category"], "price": product["price"], "features": product["features"] }], ids=[product["id"]] ) ``` ### 3. Integration Points #### A. QuickInsightAnalysis Component Replace mock similar products with ChromaDB queries: ```typescript // In segmind/frontend/components/QuickInsightAnalysis.tsx const getSimilarProducts = async (targetProduct: string) => { try { const response = await fetch('/api/chromadb/similar-products', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ product: targetProduct, limit: 5 }) }); const data = await response.json(); return data.similarProducts; } catch (error) { console.error('Error fetching similar products:', error); return []; } }; ``` #### B. Campaign Generation Use ChromaDB for product recommendations in campaigns: ```typescript // In campaign generation logic const getProductRecommendations = async (customerSegment: string, preferences: string[]) => { const response = await fetch('/api/chromadb/recommendations', { method: 'POST', headers: { 'Content-Type': 'applica [truncated — 10400 more characters] ``` ### segmind/backend/api_usage_example.md ```markdown # Campaign Cards API Usage ## Endpoint: `/api/campaigns/generate-cards` ### Method: POST ### Request Format: ```json { "product": { "name": "iPhone 15 Pro", "category": "Phones", "price": 999 }, "strategy": { "product": "iPhone 15 Pro", "primaryAudience": "Window Shoppers", "strategy": "Generate targeted informative email campaigns for window shoppers with compelling hero images and personalized content.", "emailType": "informative", "customPrompt": "" }, "weeklySchedule": [ { "day": "Monday", "time": "10:00 AM", "type": "Primary Campaign", "audience": "Window Shoppers", "emailTheme": "Discovery & Exploration" }, { "day": "Wednesday", "time": "2:00 PM", "type": "Primary Campaign", "audience": "Window Shoppers", "emailTheme": "Feature Showcase" }, { "day": "Thursday", "time": "11:00 AM", "type": "Follow-up", "audience": "Cart Abandoners", "emailTheme": "Urgency & Completion" }, { "day": "Friday", "time": "9:00 AM", "type": "Premium Drop", "audience": "High Converters", "emailTheme": "Exclusive Access" }, { "day": "Sunday", "time": "6:00 PM", "type": "Weekly Recap", "audience": "All Segments", "emailTheme": "Weekly Highlights" } ] } ``` ### Response Format: ```json { "success": true, "cards": [ { "id": "card_1729909876_0", "day": "Monday", "time": "10:00 AM", "type": "Primary Campaign", "audience": "Window Shoppers", "theme": "Modern & Clean", "subject": "Meet the Future: Introducing iPhone 15 Pro", "preview": "Monday 10:00 AM: Primary Campaign", "prompt": "Primary Campaign email for Window Shoppers promoting iPhone 15 Pro", "emailContent": "Hi {{first_name}},\n\nWe're excited to introduce you to the iPhone 15 Pro!\n\nAs someone who appreciates quality technology, we thought you'd love to know about this latest addition to our collection.\n\n✨ Key Features:\n• Premium design and build quality\n• Latest technology innovations\n• Perfect for your lifestyle\n\nReady to learn more?\n\nBest regards,\nThe Segmind Team", "imagePrompt": "Clean, modern product photography of iPhone 15 Pro on a minimal white background with soft studio lighting, professional commercial style", "status": "pending" } ], "generated_at": "2025-10-26T04:34:15.123456", "total_cards": 5 } ``` ## Frontend Integration ### Replace the existing Next.js API call In your frontend `generateCampaignCards` function, replace: ```javascript // OLD: Next.js API const response = await fetch('/api/generate-campaign-cards', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ product: selectedProductForPromotion, strategy: strategy, weeklySchedule: strategy.weeklySchedule }) }) ``` ### With the new FastAPI backe [truncated — 2338 more characters] ``` ### requirements.txt ``` <<<<<<< HEAD requests==2.31.0 pandas==2.1.4 python-dotenv==1.0.0 chromadb==0.4.22 ======= google-generativeai pillow python-dotenv >>>>>>> 072a80908f4936a1092d1494cd35466436e8fc9b ``` ### docker-compose.yml ```yaml services: backend: build: context: . dockerfile: Dockerfile.backend ports: - "8000:8000" volumes: - ./segmind/backend:/app - ./.env:/app/.env environment: - PYTHONUNBUFFERED=1 networks: - segmind-network frontend: build: context: . dockerfile: Dockerfile.frontend ports: - "3000:3000" volumes: - ./segmind/frontend:/app - ./.env:/app/.env - /app/node_modules environment: - DOCKER_ENV=true - OPENAI_API_KEY=${OPENAI_API_KEY} - SUPABASE_URL=${SUPABASE_URL} - SUPABASE_ANON_KEY=${SUPABASE_ANON_KEY} depends_on: - backend networks: - segmind-network networks: segmind-network: driver: bridge ``` ### segmind/requirements.txt ``` fastapi==0.104.1 uvicorn[standard]==0.24.0 pydantic==2.5.1 python-dotenv==1.0.0 pandas==2.1.4 numpy==1.24.3 sqlalchemy==2.0.23 psycopg2-binary==2.9.9 httpx==0.25.2 python-multipart==0.0.6 jinja2==3.1.2 python-jose[cryptography]==3.3.0 passlib[bcrypt]==1.7.4 redis==5.0.1 celery==5.3.4 requests==2.31.0 ``` ### segmind/docker-compose.yml ```yaml services: frontend: build: context: ./frontend dockerfile: Dockerfile ports: - "3000:3000" volumes: - ./frontend:/app - /app/node_modules - /app/.next environment: - NODE_ENV=development - CHOKIDAR_USEPOLLING=true command: npm run dev stdin_open: true tty: true restart: unless-stopped # Add more services here as needed (backend, database, etc.) ``` ### segmind/frontend/requirements.txt ``` requests>=2.31.0 ``` ### segmind/backend/requirements.txt ``` fastapi==0.115.6 uvicorn[standard]==0.32.1 chromadb==0.4.24 supabase==2.12.0 python-multipart==0.0.6 python-dotenv==1.0.0 requests==2.31.0 numpy==1.26.4 pillow==10.1.0 google-genai==1.46.0 ``` ### segmind/frontend/Dockerfile ``` FROM node:18-alpine WORKDIR /app # Copy package files COPY package*.json ./ # Install dependencies RUN npm ci # Copy source code COPY . . # Expose port EXPOSE 3000 # Start development server CMD ["npm", "run", "dev"] ``` ### segmind/frontend/package.json ``` { "name": "segmind-frontend", "version": "1.0.0", "private": true, "scripts": { "dev": "next dev", "build": "next build", "start": "next start", "lint": "next lint" }, "dependencies": { "next": "14.0.0", "react": "^18.2.0", "react-dom": "^18.2.0", "typescript": "^5.2.2", "@types/node": "^20.8.0", "@types/react": "^18.2.25", "@types/react-dom": "^18.2.11", "tailwindcss": "^3.3.5", "autoprefixer": "^10.4.16", "postcss": "^8.4.31", "axios": "^1.5.0", "recharts": "^2.8.0", "lucide-react": "^0.292.0", "@radix-ui/react-tabs": "^1.0.4", "@radix-ui/react-dialog": "^1.0.5", "@radix-ui/react-select": "^2.0.0", "class-variance-authority": "^0.7.0", "clsx": "^2.0.0", "tailwind-merge": "^2.0.0" }, "devDependencies": { "eslint": "^8.52.0", "eslint-config-next": "14.0.0" } } ``` [78 more indexed source files omitted to keep this export small. The full file list is in the Codebase structure section above.]