RevenueGuard — Automated Revenue Recovery Platform

RevenueGuard is a real-time revenue recovery platform designed to detect and recover lost revenue across subscription billing failures, cart abandonment, churn cancellations, and high-value refund disputes.

It combines high-throughput deterministic pattern detection (<1ms) with an intelligent recovery agent bounded by strict business policies, executing idempotent tools and measuring incremental revenue via randomized A/B holdout testing.

---

Architecture Overview

Events (Stripe, Shopify, SaaS Billing, Support)
   │
   ▼
[ 1. Ingestion & Fast Leakage Detection ]  ──> Regex / Domain Rules (<1ms)
   │
   ▼
[ 2. Triage & ERV Scoring ]  ────────────────> Expected Recovery Value calculation
   │
   ├──> Control Group (50% Holdout) ─────────> Natural baseline tracking
   └──> Treatment Group (50%)
          │
          ▼
       [ 3. Recovery Agent (LangGraph) ] ────> Evaluates customer context & strategy
          │
          ▼
       [ 4. Deterministic Policy Engine ] ───> Hard constraints (caps, limits, margins)
          │
          ├──> Approved Automatically ───────> Typed Recovery Tools (Stripe, Email, etc.)
          └──> High-Risk Concession ─────────> Human-in-the-Loop Review Queue

---

Access Types & User Roles (RBAC)

RevenueGuard includes built-in role-based access control across both the API and the interactive mission control dashboard. You can switch between roles using the role selector in the dashboard header:

Role	Access Level	Permissions & Capabilities
ADMIN	Full Administrative Access	• Authorize & reject high-risk Human-in-the-Loop concessions (credits > ₹500, large refunds) • Trigger simulator event scenarios • Modify deterministic policy limits and margin guards • Full system audit trail access
OPERATOR	Operational Actions	• Monitor real-time opportunity queues and recovery pipelines • Trigger standard recovery workflows • High-risk interventions are automatically routed to Admin queue
VIEWER	Read-Only Audit	• Inspect executive KPI metrics, conversion rates, and causal A/B lift • View event streams and customer diagnostic traces • Modification and approval buttons are disabled

API Authentication & Access Methods

• Demo Key Access: Include header X-API-Key: demo-admin-key for frictionless admin testing.
• JWT Bearer Token: Obtain via POST /api/v1/auth/login and pass as Authorization: Bearer <token>.
• Interactive Swagger Documentation: Available at http://localhost:8000/docs.

---

Core Features

1. Deterministic Leakage Detection: Filters payment failures, abandoned checkouts, and cancellation events without burning expensive LLM calls on detection.
2. Mathematical Triage Scoring (ERV): $$\text{ERV} = (\text{Revenue at Risk} \times \text{Recovery Probability}) - \text{Intervention Cost}$$
3. Hard Policy Invariants:
   • Maximum discount cap: $\le 10%$
   • Automatic account credit cap: $\le$ ₹500 (credits above require Admin authorization)
   • Contact frequency cap: Maximum 2 touches in rolling 7 days
   • Margin guard: Total concessions must not exceed 20% of customer LTV
4. Causal Attribution (A/B Testing):
   • Consistent hashing splits opportunities into Control (Holdout) and Treatment.
   • Accurately computes true incremental lift rather than falsely claiming organic renewals.

---

Project Structure

revenueguard/
├── apps/
│   ├── api/                  # FastAPI backend server
│   │   ├── main.py           # Application entrypoint & lifespan
│   │   ├── dependencies.py   # RBAC & authentication
│   │   └── routers/          # Events, opportunities, decisions, approvals, simulator
│   └── dashboard/            # Next.js 14 executive mission control
│       ├── app/              # Dashboard pages (live, opportunities, approvals, etc.)
│       └── components/       # Reusable UI components & role switcher
├── services/
│   ├── detector/             # Revenue leakage detection rules (<1ms)
│   ├── recovery/             # ERV scoring & opportunity lifecycle
│   ├── experimentation/      # Consistent salt-hash A/B assignment
│   └── attribution/          # Causal counterfactual lift engine
├── agents/
│   └── recovery_agent/       # LangGraph state machine & context builder
├── packages/
│   ├── common/               # Configurations, logging, and security
│   ├── database/             # SQLAlchemy ORM models & session management
│   ├── event_schemas/        # Pydantic schemas for domain events
│   ├── policies/             # Deterministic business rule invariants
│   └── tools/                # Idempotent execution tools (Stripe, email, credit)
├── simulator/                # Scenario runners and synthetic event streams
└── tests/                    # Unit, integration, and e2e test suite

---

Quickstart

Prerequisites

• Python: 3.11 or higher
• Node.js: 20 or higher
• npm or pnpm

1. Backend Setup

# Install Python dependencies
pip install -r requirements.txt

# Run test suite
pytest tests/unit tests/integration -v

# Start FastAPI backend
python -m uvicorn apps.api.main:app --port 8000

• API is live at http://localhost:8000
• Interactive API Docs at http://localhost:8000/docs

2. Frontend Setup

# In a new terminal
cd apps/dashboard
npm install
npm run dev

• Open http://localhost:3000 in your browser.
• Visit http://localhost:3000/live to view the live interactive philosophy demo.

---

Production Configuration

To switch from the local SQLite/mock environment to production, update your .env:

# Production PostgreSQL
DATABASE_URL=postgresql+asyncpg://user:password@localhost:5432/revenueguard

# Real LLM Provider (OpenAI / Azure / OpenRouter)
USE_MOCK_LLM=False
OPENAI_API_KEY=sk-...
LLM_MODEL=gpt-4o-mini

# Cache & Message Broker (Optional for high volume)
REDIS_ENABLED=True
REDIS_URL=redis://localhost:6379/0
KAFKA_ENABLED=False

---

Running Tests

# Run unit & integration tests
pytest tests/unit tests/integration -v

---

Author

Maintained by Rashmi (rashmi@bitspeed.com).