SuccessHelix 🧬

AI-Powered Customer Success Platform with Tableau Integration

Transform customer health metrics into actionable intelligence. SuccessHelix uses enterprise-grade ML churn prediction with SHAP explainability, AI-powered insights, and native Tableau Cloud embedding.

Overview

SuccessHelix treats customer health as DNA - four interconnected "genes" that determine relationship health:

Gene	Metrics	What it Measures
Engagement	Product usage, feature adoption, logins	Customer activity level
Financial	Payment history, ARR, expansion signals	Revenue health
Sentiment	NPS, support tickets, CSAT	Customer satisfaction
Relationship	Contact quality, meetings, sponsorship	Relationship strength

Key Features

Feature	Technology	Description
Genome Visualization	D3.js	Interactive DNA-style view of customer health
Tableau Dashboards	Embedding API v3	Native Tableau Cloud embedding
ML Churn Prediction	scikit-learn + SHAP	Calibrated classifier with feature explainability
AI Insights	OpenRouter (Gemini 2.0)	Natural language analysis and recommendations
Data Pipeline	Hyper API	Automated data extract generation and publishing
Slack Alerts	Webhooks	Proactive health notifications

Architecture

flowchart LR
    subgraph Frontend["React Frontend (Vercel)"]
        UI[Dashboard & Analytics]
        Tableau[Tableau Embed]
        D3[D3.js Genome]
    end

    subgraph Backend["FastAPI Backend (Google Cloud Run)"]
        API[REST APIs]
        ML[ML + SHAP]
        Hyper[Hyper API]
    end

    subgraph External["External Services"]
        TC[Tableau Cloud]
        OR[OpenRouter]
        SL[Slack]
    end

    UI --> API
    Tableau --> TC
    API --> ML
    API --> Hyper --> TC
    API --> OR
    API --> SL

🌐 Live Demo

Component	URL
Frontend	success-helix.vercel.app
Backend API	successhelix-api-1064261519338.europe-west1.run.app

Deployment Stack

Frontend: Vercel (React + Vite)
Backend: Google Cloud Run (containerized FastAPI)
Tableau: Tableau Cloud (prod-in-a.online.tableau.com)

sequenceDiagram
    participant U as User
    participant F as Frontend
    participant B as Backend
    participant T as Tableau Cloud

    U->>F: Click Refresh Data
    F->>B: POST /api/tableau/cloud/publish
    B->>B: Generate .hyper file
    B->>T: Publish datasource
    T-->>B: Success
    B-->>F: {success: true}
    F->>T: Reload dashboard

🚀 Quick Start

Prerequisites

Python 3.10+
Node.js 18+
OpenRouter API key (free tier available)

Installation

# Clone the repository
git clone https://github.com/N-45div/SuccessHelix.git
cd SuccessHelix

# Install Python backend dependencies
cd backend-python
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
pip install -r requirements.txt

# Install frontend dependencies
cd ../frontend
npm install

Configuration

Python Backend - Copy .env.example to .env:

cd backend-python
cp .env.example .env

Add your OpenRouter API key:

OPENROUTER_API_KEY=sk-or-v1-xxxxxxxxxxxxx

Get a free API key at: https://openrouter.ai/keys

Running the Application

# Terminal 1: Start Python backend (port 8001)
cd backend-python
source venv/bin/activate
uvicorn app.main:app --reload --port 8001

# Terminal 2: Start frontend (port 3000)
cd frontend
npm run dev

Open http://localhost:3000 to view the application.

📁 Project Structure

SuccessHelix/
├── backend-python/           # Python FastAPI backend
│   ├── app/
│   │   ├── main.py          # FastAPI application
│   │   ├── routers/
│   │   │   ├── health.py    # Customer health endpoints
│   │   │   ├── tableau.py   # Hyper API & Tableau integration
│   │   │   └── ai.py        # AI analytics endpoints
│   │   ├── services/
│   │   │   ├── hyper_service.py   # Tableau Hyper API
│   │   │   ├── ml_service.py      # ML churn prediction
│   │   │   └── ai_service.py      # OpenRouter AI
│   │   ├── models/
│   │   │   └── customer.py        # Pydantic models
│   │   └── data/
│   │       └── customers.py       # Customer data store
│   ├── requirements.txt
│   └── .env.example
│
├── frontend/                 # React TypeScript frontend
│   ├── src/
│   │   ├── components/
│   │   │   ├── GenomeVisualization.tsx  # D3.js genome viz
│   │   │   └── ui/                       # shadcn/ui components
│   │   ├── pages/
│   │   │   ├── Dashboard.tsx    # Main dashboard
│   │   │   ├── Analytics.tsx    # AI + Tableau analytics
│   │   │   ├── Portfolio.tsx    # Customer portfolio
│   │   │   └── CustomerDetail.tsx
│   │   └── lib/
│   │       └── api.ts           # API client
│   └── package.json
│
└── README.md

🔌 API Endpoints

Health Endpoints

Endpoint	Method	Description
`/api/health/portfolio`	GET	Get portfolio health summary
`/api/health/customers`	GET	List all customers
`/api/health/customer/:id`	GET	Get customer health details
`/api/health/customer/:id/genome`	GET	Get D3.js genome visualization data
`/api/health/export/csv`	GET	Export data as CSV for Tableau

Tableau Endpoints

Endpoint	Method	Description
`/api/tableau/generate-hyper`	POST	Generate all .hyper files
`/api/tableau/hyper/customer-health`	GET	Generate customer health .hyper
`/api/tableau/hyper/gene-scores`	GET	Generate gene scores .hyper
`/api/tableau/embed-config`	GET	Get Tableau embed configuration
`/api/tableau/cloud/status`	GET	Verify Tableau Cloud publish config
`/api/tableau/cloud/publish/customer-health`	POST	Publish Hyper datasource to Tableau Cloud

ML Endpoints

Endpoint	Method	Description
`/api/ml/status`	GET	Model trained status + last training metrics
`/api/ml/train`	POST	Deterministic model training (seed)
`/api/ml/feature-importance`	GET	Feature importance / top drivers
`/api/ml/portfolio-risk`	GET	Portfolio risk distribution + drivers

AI Analytics Endpoints

Endpoint	Method	Description
`/api/ai/portfolio-insights`	GET	AI-generated portfolio insights
`/api/ai/customer/:id/analyze`	GET	AI analysis of customer
`/api/ai/customer/:id/churn-prediction`	GET	ML + AI churn prediction
`/api/ai/ask`	POST	Natural language query
`/api/ai/alerts`	GET	Proactive AI alerts
`/api/ai/risk-analysis`	GET	Portfolio risk analysis
`/api/ai/simulate-intervention`	POST	What-if simulation

🎯 Tableau Developer APIs Used

1. Hyper API

Generate .hyper data extracts programmatically:

from tableauhyperapi import HyperProcess, Connection, TableDefinition, Inserter

# Create customer health extract
generate_customer_health_hyper()  # → customer_health.hyper
generate_gene_scores_hyper()      # → gene_scores.hyper
generate_cascade_events_hyper()   # → cascade_events.hyper

2. Embedding API v3

Interactive dashboard embedding with JavaScript:

<tableau-viz
  src="${TABLEAU_EMBEDDING_URL}"
  toolbar="bottom"
  hide-tabs
/>

3. Event Listeners

React to user interactions in embedded viz:

viz.addEventListener('marksselected', handleMarkSelection);
viz.addEventListener('filterchange', handleFilterChange);

Innovation Highlights

Innovation	Description
DNA Genome Visualization	Customer health as interconnected genes using D3.js
Enterprise ML Pipeline	CalibratedClassifierCV with SHAP explainability
AI Natural Language	Ask questions like "Which customers need attention?"
Tableau Integration	Hyper API + Embedding API v3 for full data pipeline
What-If Simulator	Test intervention strategies before committing

APIs and Developer Tools

Tool	Usage
Tableau Hyper API	Programmatic `.hyper` extract generation for customer health, gene scores, cascade events
Tableau Embedding API v3	Native `<tableau-viz>` web component embedding with event listeners
Tableau REST API	Multipart/mixed datasource publishing to Tableau Cloud
OpenRouter (Gemini 2.0 Flash)	Natural language insights, customer diagnosis, what-if simulations
scikit-learn	CalibratedClassifierCV + GradientBoostingClassifier for calibrated churn probabilities
SHAP	TreeExplainer for feature importance and individual prediction explanations
D3.js	Custom genome visualization with animated DNA strands and cascade flows
FastAPI	High-performance async Python backend with automatic OpenAPI docs
React + TypeScript	Type-safe frontend with TailwindCSS and shadcn/ui
Slack Webhooks	Proactive health alerts with interactive message blocks
Google Cloud Run	Serverless container deployment for backend API with auto-scaling
Vercel	Frontend hosting with SPA routing and edge network

License

MIT License

SuccessHelix - Proactive customer success powered by AI and Tableau.

Name		Name	Last commit message	Last commit date
Latest commit History 32 Commits
backend-python		backend-python
frontend		frontend
.gitignore		.gitignore
ARCHITECTURE.md		ARCHITECTURE.md
LICENSE		LICENSE
README.md		README.md

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

SuccessHelix 🧬

Overview

Key Features

Architecture

🌐 Live Demo

Deployment Stack

🚀 Quick Start

Prerequisites

Installation

Configuration

Running the Application

📁 Project Structure

🔌 API Endpoints

Health Endpoints

Tableau Endpoints

ML Endpoints

AI Analytics Endpoints

🎯 Tableau Developer APIs Used

1. Hyper API

2. Embedding API v3

3. Event Listeners

Innovation Highlights

APIs and Developer Tools

License

About

Uh oh!

Releases

Packages

Uh oh!

Contributors

Uh oh!

Languages

Folders and files

Latest commit

History

Repository files navigation

SuccessHelix 🧬

Overview

Key Features

Architecture

🌐 Live Demo

Deployment Stack

🚀 Quick Start

Prerequisites

Installation

Configuration

Running the Application

📁 Project Structure

🔌 API Endpoints

Health Endpoints

Tableau Endpoints

ML Endpoints

AI Analytics Endpoints

🎯 Tableau Developer APIs Used

1. Hyper API

2. Embedding API v3

3. Event Listeners

Innovation Highlights

APIs and Developer Tools

License

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages