HackHounds26 – AI Funnel Intelligence

Devpost-style overview of the project, stack, and how to run it locally for demos.

🙌 Inspiration

Teams drown in product analytics dashboards but still guess why users drop off. We wanted a single pane that shows raw funnel data and an AI narrative side-by-side so PMs can decide what to fix immediately.

💡 What it does

• Collects product events into a Rails + Postgres backend.
• Aggregates funnel metrics (counts, conversion %, avg step time, device/country mix).
• Sends a structured payload to a FastAPI AI microservice (Gemini via google-genai), returning the biggest issue, reason, and a 3-step playbook.
• Frontend dashboard shows AI insights on the left, live funnel data on the right, with conversion bars per step.

🏗️ How we built it

• Backend API: Ruby on Rails 7 + Postgres + Redis-ready; endpoints for events, funnels, summaries, and AI analysis.
• AI service: FastAPI (Python 3.11) with Google Gemini (google-genai); fallback MOCK_MODE for offline demos.
• Frontend: React + Vite (dashboard/), auth-protected dashboard consuming Rails & AI.
• Infra: Docker Compose for backend, AI, dashboard demo, and demo landing (demo/).

⚙️ Setup (local, easiest path)

Prereqs: Docker + docker-compose, Node 18+, Ruby toolchain if running Rails outside Docker.

1. Copy .env (already present) and ensure keys:
   • GOOGLE_AI_API_KEYS (comma-separated) or set MOCK_MODE=true in AI container.
   • AI_URL=http://ai:8000/analyze-funnel when using Compose, or http://localhost:8000/analyze-funnel if Rails runs on host.
2. Build & start services:

   docker compose up -d --build backend ai dashboard demo

3. Seed demo data (funnels + events):

   docker compose exec backend bundle exec rails db:setup

4. Open frontends:
   • Dashboard (auth): http://localhost:5173
   • Demo landing: http://localhost:5174
5. Run AI analysis from dashboard: pick a funnel, click “Run analysis”. Rails posts to FastAPI and returns AI JSON.

🌐 Key endpoints

• GET /funnels/:id/summary – structured funnel payload (counts, avg durations, breakdowns).
• POST /funnels/:id/analyze – forwards summary to AI service, returns AI result.
• AI: POST /analyze-funnel (FastAPI) – accepts the payload and returns the narrative.

🔑 Environment highlights

• Rails: POSTGRES_*, REDIS_URL, AI_URL
• AI: GOOGLE_AI_API_KEYS, APP_MODULE=testmain:app, optional MOCK_MODE=true
• Frontend: VITE_API_URL (Rails), VITE_AI_BASE (FastAPI), VITE_FUNNEL_ID

🧠 AI prompt shape (example)

{
  "project_id": 1,
  "funnel_id": 1,
  "funnel_name": "signup_funnel",
  "time_range": "last_7_days",
  "total_users": 1500,
  "steps": [
    { "name": "landing_page", "users": 1500, "avg_time_seconds": 12 },
    { "name": "signup_started", "users": 950, "avg_time_seconds": 25 },
    { "name": "signup_completed", "users": 500, "avg_time_seconds": 90 },
    { "name": "onboarding_completed", "users": 300, "avg_time_seconds": 180 },
    { "name": "subscription_started", "users": 120, "avg_time_seconds": 45 }
  ],
  "device_breakdown": { "mobile": 900, "desktop": 600 },
  "country_breakdown": { "US": 700, "CA": 300, "Other": 500 }
}

🧪 Demo tips

• Want deterministic output? Set MOCK_MODE=true in AI env and restart the AI container.
• If AI can’t be reached from Rails, set AI_URL to http://localhost:8000/analyze-funnel (host) or http://ai:8000/analyze-funnel (Compose network).
• Clear compiled Python files to avoid git conflicts: git rm -r --cached ai-services/FastAPI/__pycache__.

🚧 Challenges

• Cross-container DNS (Rails → FastAPI) and keeping env defaults sane for both host and Compose.
• Cleaning AI responses to guaranteed JSON while preserving markdown-stripped output.

🚀 Next up

• Multi-project auth scoping and role-based access.
• A/B test hooks to auto-ship the suggested playbook.
• Real-time stream of events to incrementally refresh funnel cards.

👥 Team

HackHounds – built for the hackathon, optimized for fast demos and clear insight delivery.