{"id":46728230,"url":"https://github.com/aiaiohhh/churn-auditor","last_synced_at":"2026-03-09T14:22:57.493Z","repository":{"id":337170974,"uuid":"1152571448","full_name":"aiaiohhh/churn-auditor","owner":"aiaiohhh","description":"AI-powered churn analysis dashboard. Gemini Flash triages, Pro diagnoses root causes, and an action engine recommends recovery. Built for the Gemini API Developer Competition.","archived":false,"fork":false,"pushed_at":"2026-02-08T10:10:47.000Z","size":170,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-02-08T12:29:31.226Z","etag":null,"topics":["ai","churn-analysis","gemini","gemini-api","hackathon","nextjs","stripe","typescript"],"latest_commit_sha":null,"homepage":"https://churn-auditor.vercel.app","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/aiaiohhh.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-02-08T04:27:16.000Z","updated_at":"2026-02-08T10:10:50.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/aiaiohhh/churn-auditor","commit_stats":null,"previous_names":["aiaiohhh/churn-auditor"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/aiaiohhh/churn-auditor","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aiaiohhh%2Fchurn-auditor","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aiaiohhh%2Fchurn-auditor/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aiaiohhh%2Fchurn-auditor/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aiaiohhh%2Fchurn-auditor/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/aiaiohhh","download_url":"https://codeload.github.com/aiaiohhh/churn-auditor/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aiaiohhh%2Fchurn-auditor/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30298670,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-09T13:46:43.843Z","status":"ssl_error","status_checked_at":"2026-03-09T13:46:42.821Z","response_time":61,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","churn-analysis","gemini","gemini-api","hackathon","nextjs","stripe","typescript"],"created_at":"2026-03-09T14:22:56.759Z","updated_at":"2026-03-09T14:22:57.486Z","avatar_url":"https://github.com/aiaiohhh.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ChurnAuditor\n\nAI-powered churn analysis dashboard that detects subscription cancellations, diagnoses root causes with Google Gemini, and executes automated recovery actions — all in under 60 seconds.\n\n**Live Demo:** https://churn-auditor.vercel.app\n**Source Code:** https://github.com/aiaiohhh/churn-auditor\n**Demo Video:** https://youtu.be/EpyM8MVg0hM\n\n## What It Does\n\nChurnAuditor turns every subscription cancellation into a recovery opportunity:\n\n- **Real-Time Detection:** Captures Stripe webhook cancellation events the moment they happen\n- **AI Root Cause Diagnosis:** Gemini cross-references support tickets, usage patterns, and exit surveys to identify exactly why the customer left\n- **Evidence Dossier:** Builds a structured intelligence report with primary cause, confidence score, supporting evidence, and save probability\n- **Smart Recovery Actions:** Automatically dispatches personalized winback emails, Linear bug tickets, and Slack alerts based on the diagnosis\n- **Live Dashboard:** Real-time feed of churn events with full dossier views, action tracking, and aggregate metrics\n\nStripe webhook fires → Gemini diagnoses root cause → Recovery actions execute → Team gets a complete dossier. All in under 60 seconds.\n\n## The Problem\n\nSaaS companies lose 5-7% of customers monthly to churn, yet most teams don't learn *why* until weeks later — if ever. The typical workflow:\n\n1. Customer cancels. Stripe sends an event. It goes into a log.\n2. Days later, someone notices the MRR drop in a dashboard.\n3. A CS rep manually reviews the account, digs through support tickets, checks usage data.\n4. By the time the team understands the reason, the customer is long gone.\n\nThe root cause data exists — scattered across support tickets, usage analytics, exit surveys, and billing records. But no one has time to synthesize it in the critical window after cancellation when the customer can still be saved.\n\n## The Solution\n\nChurnAuditor collapses that multi-day manual process into a 60-second automated pipeline powered by Gemini AI.\n\nInstead of a human analyst spending hours piecing together signals, Gemini ingests all available customer context, identifies the primary churn driver, assesses save probability, and triggers the right recovery action — automatically.\n\nThe result: your team gets an actionable intelligence dossier before the customer has even finished their cancellation flow.\n\n## Technical Architecture\n\n### AI Model: Gemini 3\n\nChurnAuditor is built on **Google's Gemini 3** models, using a two-stage AI pipeline with intelligent model routing and structured JSON output.\n\n#### Stage 1: Triage (Gemini 3 Flash)\n\n**What It Does:**\nThe first stage performs rapid assessment of every incoming cancellation event to determine severity and analysis depth.\n\n**How It Works in ChurnAuditor:**\n- Stripe webhook fires with cancellation event data (customer name, MRR, plan, cancellation reason)\n- Event is sent to Gemini Flash at temperature 0.3 for fast, deterministic assessment\n- Flash evaluates: Is this a high-value churn that warrants deep analysis? Or a low-priority event?\n- Uses structured JSON output with a defined response schema via `@google/genai` SDK\n\n**Technical Process:**\nThe triage prompt includes the full churn event payload. Gemini Flash evaluates MRR impact, plan tier, customer tenure signals, and stated cancellation reason to produce a routing decision. The response is validated against a Zod schema for type safety.\n\n**Output:**\nA routing decision that determines whether the event goes to Gemini Pro (high-value, complex cases) or stays with Gemini Flash (straightforward, lower-impact cases) for the diagnosis stage.\n\n#### Stage 2: Diagnosis (Gemini 3 Pro or Flash)\n\n**What It Does:**\nThe second stage performs deep root cause analysis, producing a complete intelligence dossier with structured evidence and recovery recommendations.\n\n**How It Works in ChurnAuditor:**\n- Receives the churn event plus triage context\n- Runs at temperature 0.4 for balanced creativity and consistency\n- Produces a typed `ChurnDossier` via structured JSON output containing:\n  - **Primary cause** (pricing, bugs, support, competition, features, or other)\n  - **Confidence score** (0-100%)\n  - **Evidence array** with source attribution and relevance scores\n  - **Save probability** (0-100%)\n  - **Recommended actions** with priority levels and execution details\n\n**Technical Process:**\nGemini receives the customer context and generates multi-step reasoning chains to identify the root cause. It cross-references the stated cancellation reason against behavioral signals (usage patterns, support ticket sentiment, feature adoption gaps) to produce a diagnosis that goes beyond surface-level explanations.\n\nThe response schema uses the `@google/genai` SDK's `Type` enum for structured output, ensuring every field matches the expected TypeScript types. All responses are validated against Zod schemas before being stored.\n\n**Output:**\nA complete `ChurnDossier` object stored in the application state, ready for display in the dashboard and action execution.\n\n#### Stage 3: Action Engine\n\n**What It Does:**\nAutomatically dispatches recovery actions based on the AI diagnosis, without human intervention.\n\n**How It Works in ChurnAuditor:**\n\nBased on the diagnosed root cause and recommended actions, the engine dispatches:\n\n- **Winback Email:** AI-personalized email addressing the specific churn reason (e.g., pricing concern gets a discount offer; bug complaint gets a fix timeline)\n- **Linear Ticket:** Creates a bug ticket when the diagnosis identifies product issues, routed to the correct engineering team\n- **Slack Alert:** Notifies the CS team with a summary dossier for high-value accounts requiring human touch\n- **Manual Review:** Flags complex cases for account manager assessment\n\nEach action tracks execution status (pending, executing, success, failed) in the dashboard.\n\n### Complete Processing Pipeline\n\n```\nStripe Webhook ──\u003e Churn Event\n                        |\n                   Gemini Flash\n                   (Triage: 1-2s)\n                        |\n              ┌─── Worth deep analysis? ───┐\n              YES                          NO\n              |                            |\n         Gemini Pro                   Gemini Flash\n        (Diagnosis: 3-8s)           (Diagnosis: 1-3s)\n              |                            |\n              └──────────┬─────────────────┘\n                         |\n                   Action Engine\n              ┌──────┬───┴───┬──────┐\n           Linear  Email  Slack  Manual\n           Ticket  Send   Alert  Review\n```\n\n**Total Time:** Under 60 seconds from cancellation to complete dossier with recovery actions dispatched.\n\n### Resilient Fallback System\n\nIf Gemini is unavailable or times out (10s limit), ChurnAuditor auto-falls back to a deterministic demo mode:\n\n- Uses a hash-based algorithm seeded from the customer ID for consistent results\n- Produces realistic dossiers with plausible evidence, causes, and recommendations\n- Ensures the app always works for demos and presentations, with or without an API key\n\n## Technology Stack\n\n**AI/ML:**\n- Gemini 3 Flash (triage) and Gemini 3 Pro (deep diagnosis)\n- `@google/genai` SDK with structured JSON output and `Type` enum schemas\n\n**Framework:**\n- Next.js 16 (App Router) with React 19\n- TypeScript in strict mode with `noUncheckedIndexedAccess`\n\n**Payments:**\n- Stripe SDK for webhook ingestion and subscription event capture\n\n**Validation:**\n- Zod 4 for schema-first type safety across all API boundaries\n\n**Styling:**\n- Tailwind CSS 4 with OKLCH color space\n- shadcn/ui component primitives\n- Custom glassmorphism design system with Google Blue palette\n\n**Infrastructure:**\n- Vercel (deployment and serverless functions)\n- In-memory Map store (hackathon MVP)\n- GitHub (version control)\n\n## Key Features\n\n### Real-Time Churn Feed\n- Live-updating event feed with polling (2s interval)\n- Status badges: Analyzing, Triaging, Complete, Failed\n- MRR impact and save probability at a glance\n- Click any event to open its full dossier\n\n### AI-Powered Dossier\n- Primary cause classification with confidence percentage\n- Evidence cards with source attribution (support tickets, usage data, surveys)\n- Relevance scoring per evidence item\n- Save probability gauge with visual indicator\n- Expandable AI reasoning chain showing how the diagnosis was reached\n\n### Smart Action Center\n- Tabbed view of all recommended recovery actions\n- Per-action execution status tracking (pending → executing → success/failed)\n- Action descriptions personalized to the specific churn diagnosis\n- One-click action execution\n\n### Aggregate Metrics\n- Total events analyzed\n- Average confidence score across all diagnoses\n- Average save rate\n- Churn cause breakdown with horizontal bar chart\n- Historical trend visualization\n\n### Simulate Mode\n- One-click churn event simulation with realistic fake customer data\n- 10 pre-built customer profiles across Starter, Pro, and Enterprise tiers\n- Randomized cancellation reasons for varied AI responses\n- Works without any API keys (demo fallback mode)\n\n## How Gemini 3 Makes This Possible\n\n### Why a Two-Stage Pipeline Matters\n\nA naive approach would send every cancellation event to a single large model. ChurnAuditor's two-stage pipeline is smarter:\n\n**Stage 1 (Flash)** is fast and cheap — it handles the 80% of events that are straightforward in 1-2 seconds. Only complex, high-value cases get routed to the more capable model.\n\n**Stage 2 (Pro)** brings deeper reasoning for the 20% of cases that need it — enterprise churn, ambiguous signals, multi-factor causes.\n\nThis architecture reduces latency by 3-5x and cost by 60-70% compared to routing everything through Pro, while maintaining diagnostic quality where it matters most.\n\n### Structured Output is Critical\n\nChurnAuditor doesn't parse free-text AI responses with regex. It uses Gemini's native structured JSON output with the `@google/genai` SDK's `Type` enum to define exact response schemas:\n\n```typescript\nresponseSchema: {\n  type: Type.OBJECT,\n  properties: {\n    primaryCause: { type: Type.STRING, enum: [...] },\n    confidence: { type: Type.NUMBER },\n    evidence: { type: Type.ARRAY, items: { ... } },\n    saveProbability: { type: Type.NUMBER },\n    recommendedActions: { type: Type.ARRAY, items: { ... } },\n  }\n}\n```\n\nEvery AI response is guaranteed to match the expected TypeScript types. No parsing failures. No hallucinated field names. This is what makes it possible to pipe AI output directly into automated action execution without human review.\n\n### Reasoning + Action in One Pipeline\n\nTraditional churn analysis tools produce reports. ChurnAuditor produces *actions*.\n\nGemini's reasoning capabilities allow the system to not just identify the root cause, but also determine the optimal recovery strategy for that specific situation. A pricing complaint triggers a discount offer email. A bug report creates a Linear ticket. A competitor switch triggers a Slack alert to the account manager.\n\nThis reasoning-to-action pipeline is only possible because Gemini can:\n1. Understand the nuanced context of why someone left\n2. Assess the probability of recovery\n3. Recommend specific, actionable interventions\n4. Structure all of this as typed data that an action engine can execute\n\n## Use Cases\n\n**SaaS Startups:**\nCatch churn early when every customer matters. Automated recovery actions mean a 2-person team can respond like a 20-person CS organization.\n\n**Growth-Stage Companies:**\nScale churn response without scaling headcount. Route high-value accounts to humans and automate the rest.\n\n**Product Teams:**\nAggregate churn causes to identify systemic product issues. If 40% of churn is \"bugs,\" that's a product roadmap signal, not just a CS problem.\n\n**Customer Success Teams:**\nGet complete context before reaching out. Instead of \"Hi, we noticed you canceled,\" it's \"Hi Sarah, we saw the dashboard loading issues you reported and have a fix shipping this week.\"\n\n**Revenue Operations:**\nTrack save rates, recovery action effectiveness, and churn cause trends over time to optimize retention strategy.\n\n## Hackathon Context\n\n**Event:** Gemini 3 Hackathon 2026\n**Category:** Business Applications / Productivity Tools\n**Platform:** Next.js on Vercel with Gemini API\n\n### Why This Project for Gemini 3\n\n**Showcases Structured Output:**\nEvery AI response uses Gemini's native structured JSON output with typed schemas — demonstrating production-grade AI integration, not just chat wrappers.\n\n**Intelligent Model Routing:**\nTwo-stage pipeline (Flash → Pro) demonstrates cost-effective, latency-optimized architecture that routes based on event complexity.\n\n**Real-World Impact:**\nSaaS churn is a $1.6 trillion annual problem. ChurnAuditor addresses it with AI automation that's immediately deployable.\n\n**End-to-End Pipeline:**\nNot just analysis — ChurnAuditor goes from webhook to diagnosis to action execution, showing Gemini powering a complete automated workflow.\n\n**Production Ready:**\nType-safe schemas, resilient fallback system, real-time dashboard, Stripe integration — built to ship, not just demo.\n\n### Gemini 3 Advantage\n\nThis application leverages capabilities specific to Gemini 3:\n\n**Structured Output:** Native JSON schema enforcement eliminates parsing errors and enables direct action execution from AI responses\n**Reasoning Depth:** Multi-factor churn diagnosis requires weighing conflicting signals — pricing complaints vs actual usage patterns vs support history\n**Speed:** Flash processes triage in 1-2 seconds, enabling real-time response to cancellation events\n**Model Routing:** Flash + Pro combination optimizes for both speed and depth based on case complexity\n\n## Getting Started\n\n```bash\n# Install dependencies\nnpm install\n\n# Set up environment variables\ncp .env.example .env.local\n# Add your GEMINI_API_KEY to .env.local (optional — demo mode works without it)\n\n# Run the dev server\nnpm run dev\n```\n\nOpen [https://churn-auditor.vercel.app](https://churn-auditor.vercel.app) and click **Simulate Cancellation** to trigger an AI analysis.\n\n### Environment Variables\n\n| Variable | Required | Description |\n|----------|----------|-------------|\n| `GEMINI_API_KEY` | No* | Google Gemini API key |\n| `STRIPE_SECRET_KEY` | No | Stripe secret key (optional for dev) |\n| `STRIPE_WEBHOOK_SECRET` | No | Stripe webhook signing secret (optional for dev) |\n\n*Demo fallback mode works without any API keys — the app is fully functional for demos.\n\n## Project Structure\n\n```\nsrc/\n  app/\n    (dashboard)/dashboard/  # Main dashboard page + layout\n    (marketing)/            # Landing page\n    api/\n      analyze/              # AI analysis endpoint + [id] polling\n      actions/              # Recovery action execution\n      webhooks/stripe/      # Stripe webhook handler\n  components/\n    churn/                  # ChurnFeed, DossierView, ActionCenter, MetricsChart, SimulateButton\n    landing/                # Hero, Features, LiveDemo, FAQ, CTA, Navbar, Footer\n    ui/                     # shadcn/ui primitives\n  lib/\n    gemini/                 # AI pipeline: agent.ts, client.ts, demo-fallback.ts\n    schemas/                # Zod schemas (single source of truth for all types)\n    tools/                  # AI tool definitions + executor\n    integrations/           # Email, Linear, Slack dispatchers\n    prompts/                # AI prompt templates\n```\n\n## Performance Metrics\n\n**Analysis Speed:** Under 60 seconds end-to-end (triage + diagnosis + action dispatch)\n**Triage Latency:** 1-2 seconds (Gemini Flash)\n**Diagnosis Latency:** 3-8 seconds (Gemini Pro) / 1-3 seconds (Gemini Flash)\n**Fallback Activation:** 10 second timeout, then instant deterministic fallback\n**Dashboard Polling:** 2 second interval for real-time updates\n**Supported Plans:** Starter, Pro, Enterprise tier routing\n\n## Future Development Roadmap\n\n### Phase 1: Post-Hackathon\n- Persistent database (Supabase / Postgres) replacing in-memory store\n- Real Stripe webhook integration with live subscription data\n- Email delivery via Resend/SendGrid\n- Slack Bot with interactive dossier cards\n\n### Phase 2: Intelligence\n- Historical churn pattern analysis and trend detection\n- Cohort-based churn prediction (identify at-risk customers before they cancel)\n- A/B testing framework for recovery action effectiveness\n- Custom action templates per churn cause\n\n### Phase 3: Scale\n- Multi-tenant architecture with team workspaces\n- Webhook support for Paddle, Chargebee, Recurly\n- CRM integrations (HubSpot, Salesforce)\n- API access for custom integrations\n- Weekly churn intelligence reports\n\n## Team\n\nBuilt by the ChurnAuditor team for the Gemini 3 Hackathon 2026.\n\n## Technology Acknowledgments\n\n**Powered by:** Google Gemini 3 (Flash + Pro)\n**Built with:** Next.js 16, React 19, TypeScript, Tailwind CSS 4\n**Deployed on:** Vercel\n**Payments:** Stripe SDK\n\n## Links\n\n**Live Demo:** https://churn-auditor.vercel.app\n**Source Code:** https://github.com/aiaiohhh/churn-auditor\n**Demo Video:** https://youtu.be/EpyM8MVg0hM\n**Hackathon:** https://gemini3.devpost.com\n\n## License\n\nMIT\n\n---\n\n**ChurnAuditor** — Turning every cancellation into a recovery opportunity with Gemini 3 AI.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faiaiohhh%2Fchurn-auditor","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Faiaiohhh%2Fchurn-auditor","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faiaiohhh%2Fchurn-auditor/lists"}