☠️ Dead Reckoning

The Revenue Truth for Agents. Dead Reckoning is an AI-powered revenue intelligence agent that detects hidden leakage across your entire SaaS stack (Stripe, HubSpot, Mixpanel, Intercom) using local-first SQL execution and Llama-3 reasoning.

⚡️ The Engine

Modern revenue data is fragmented. Dead Reckoning fixes this by using the Coral Model Context Protocol (MCP) to execute federated SQL across your disparate data silos, pulling the exact truth into a central intelligence loop where Groq (Llama-3 70B) analyzes the patterns and outputs actionable narratives.

No brittle ETL pipelines. No stale BI dashboards. Just an agent asking: "Where is the revenue leaking today?"

🔍 Core Leakage Patterns Detected

Dead Reckoning constantly monitors your data for 5 critical SaaS revenue leakage patterns:

1. 👻 Ghost Accounts: High-value customers paying but completely inactive (High Churn Risk).
2. 🐛 Bug-Blocked Deals: Sales deals stalled specifically because of open engineering bugs.
3. ⏳ Silent Churn: The countdown combining support ticket volume, usage drop-offs, and CRM silence.
4. 🧟 Zombie Invoices: Deals marked "Closed Won" in CRM but never actually billed in Stripe.
5. 📈 Expansion Blind Spots: Power users hitting plan limits who haven't been touched by sales.

🛠 Tech Stack

Dead Reckoning is built on a highly modern, local-first intelligence stack designed for extreme speed and precision.

Frontend Layer

• Next.js 16 (App Router): Powers the unified React server/client architecture for the dashboard.
• Tailwind CSS v4: Used for atomic, utility-first styling.
• Recharts: Renders the pattern distribution scatter plot for risk analysis.
• Design System: The UI is strictly governed by a "Nautical Dark Room" aesthetic (Base #0a0a0a), heavily utilizing JetBrains Mono for technical data legibility, Syne for expressive headers, and ultra-precise 0.5px hairline borders.

Intelligence & Execution Layer

• Groq SDK (Llama 3.3 70b Versatile): The brain of the agent. Chosen specifically for its sub-second inference speeds, Groq powers the analytical scoring, natural language translation, and the conversational "Ask" interface.
• Coral Model Context Protocol (MCP): The execution muscle. Coral allows the agent to write and execute standard SQL queries that instantly federate across APIs (Stripe, HubSpot, Mixpanel, Intercom, GitHub) without requiring an intermediate data warehouse or ETL pipeline.
• Commander.js & TSX: Powers the extensive CLI toolchain for headless agent operations (npm run scan, npm run ask).
• Slack Webhooks: For real-time, highly formatted notification dispatch.

🚀 Getting Started

1. Environment Setup

Clone the repository and install dependencies:

npm install

Create a .env.local file in the root directory:

GROQ_API_KEY=your_groq_api_key_here
SLACK_WEBHOOK_URL=https://hooks.slack.com/services/YOUR/WEBHOOK/HERE
SLACK_CHANNEL=#revenue-intelligence

2. The Mock Fallback (No live DB required!)

To test the agent immediately without connecting live databases, run the seed script. This generates a mock database of highly realistic leaking accounts:

npx tsx src/scripts/seed-demo-data.ts

The system will automatically detect if Coral is unconfigured and seamlessly fall back to querying this mock data!

3. Launching the Dashboard

Fire up the Nautical Dark Room dashboard:

npm run dev

Visit http://localhost:3000. You can force a scan or chat with the agent directly from the embedded terminal drawer.

4. Developer CLI Operations

Dead Reckoning is agent-first and fully operable from your terminal.

# Run a full risk scan and output a terminal table
npm run scan

# Ask the agent a custom natural language query
npm run ask "Which accounts are churning?"

# Generate an executive summary briefing
npm run briefing

# Run continuous monitoring (Cron mode)
npm run watch --interval 15

🧠 Architecture Overview

Dead Reckoning utilizes a closed-loop intelligence architecture. Data is never moved into a warehouse; instead, the agent pulls the exact data it needs, in real-time, to score accounts and generate narratives.

Core System Flow

flowchart LR
    %% Define Styles
    classDef source fill:#1a1a1a,stroke:#444,stroke-width:1px,color:#aaa,rx:5px,ry:5px
    classDef engine fill:#1a1a1a,stroke:#d4af37,stroke-width:2px,color:#fff,rx:10px,ry:10px
    classDef ai fill:#1a1a1a,stroke:#00a3cc,stroke-width:2px,color:#fff,rx:10px,ry:10px
    classDef output fill:#1a1a1a,stroke:#22c55e,stroke-width:2px,color:#fff,rx:5px,ry:5px

    %% 1. Where data lives
    subgraph step1 [Step 1: Messy Data Silos]
        direction TB
        S(Stripe Billing)
        H(HubSpot CRM)
        I(Intercom Support)
    end
    S:::source
    H:::source
    I:::source

    %% 2. The Engine
    subgraph step2 [Step 2: Data Extraction]
        direction TB
        C{{"Coral MCP Engine<br/>(Translates SQL into<br/>cross-platform API calls)"}}
    end
    C:::engine

    %% 3. The Brain
    subgraph step3 [Step 3: AI Intelligence]
        direction TB
        R["Risk Scorer<br/>(Flags leaking accounts)"]
        L(("Groq Llama-3 AI<br/>(Reads raw data &<br/>writes analyst narratives)"))
        R -->|Sends high-risk data| L
    end
    R:::ai
    L:::ai

    %% 4. The Action
    subgraph step4 [Step 4: Actionable Insights]
        direction TB
        UI["Web Dashboard<br/>(Visualizing metrics)"]
        Slack["Slack Alerts<br/>(Notifying the team)"]
    end
    UI:::output
    Slack:::output

    %% Flow Connections
    S -.-> C
    H -.-> C
    I -.-> C
    
    C ===>|"Returns unified data rows"| R
    L ===>|"Delivers final reports"| UI
    L ===>|"Alerts for scores > 80"| Slack

Loading

The Conversational "Ask" Loop

When users interact with the Chat Drawer or the npm run ask CLI, the architecture shifts to a dynamic Tool-Use loop:

sequenceDiagram
    participant U as User / UI
    participant A as Agent Orchestrator
    participant L as Groq (Llama-3)
    participant C as Coral MCP (SQL)
    participant D as Data Sources
    
    U->>A: "Which accounts are churning?"
    A->>L: Request with Context & Schema
    Note over L: LLM reasons and<br/>decides it needs data
    L->>A: Tool Call: execute_sql(query)
    A->>C: mcp.query("SELECT ...")
    C->>D: Federated Request
    D-->>C: JSON Rows
    C-->>A: Query Results
    A->>L: Tool Result (Data)
    Note over L: LLM analyzes the raw<br/>data to form an answer
    L-->>A: Final Natural Language Answer
    A-->>U: "Here are the churning accounts..."

Loading

Module Breakdown

• src/app/: The Next.js frontend, housing the dashboard UI and API routes (/api/leakage) that trigger the agent.
• src/agent/index.ts: The core AI orchestrator. Handles pattern scoring, alert thresholds, and manages the Groq tool-use loop.
• src/coral/client.ts: The MCP interface wrapper. Manages the lifecycle of the Coral binary and handles the seamless fallback to mock data (coral/mock-data.json) if the live binary is unavailable.
• src/coral/queries.ts: The repository of complex, cross-source SQL queries used during the automated scanning phase (e.g., BUG_BLOCKED_DEALS_SQL).
• src/outputs/: Dedicated modules for rendering rich terminal tables and formatting external Slack webhooks.

🤝 Integrating Live Data (Coral Configuration)

To connect Dead Reckoning to your live production data, you must configure the Coral engine. Update the coral/config.yaml file with your actual connection credentials for PostgreSQL, Stripe, HubSpot, etc. Once the engine is authenticated, npm run scan will automatically begin executing federated SQL against your live data stack.

🛡 License

MIT License. See LICENSE for more information.