Business Intelligence Engine — Architecture

Status: Active module

Note

This module predates the Graph architecture and provides enterprise-grade analytics for business questions. It is complementary to, not a replacement for, the Graph Orchestrator.

Overview

The Business Intelligence Engine is a sophisticated analytics service that transforms natural language business questions into actionable insights. It combines intent recognition, smart SQL generation, and executive summary capabilities.

graph TD
    A[User Question] --> B[Intent Recognition]
    B --> C[Metric Extraction]
    C --> D[Data Source Selection]
    D --> E[Query Generation]
    E --> F[Analytics Execution]
    F --> G[Metric Calculation]
    G --> H[Insight Generation]
    H --> I[Response Formatting]

Core Capabilities

1. Intent Detection

The engine classifies business questions into distinct intents:

Intent	Trigger Patterns	Example
FRAUD	"fraud", "suspicious", "risk"	"Why was this player paid?"
COMPARISON	"compare", "vs", "how we did"	"Compare this week vs last week"
SIMPLE	"total", "count", "how many"	"What is the total GGR?"
TREND	"progress", "change", "performance"	"How is the performance this month?"

2. Timeframe Extraction

Automatically detects temporal references:

Absolute: "January 2026", "March 15"
Relative: "yesterday", "last week", "this month"
Ranges: "last 7 days", "Q1 2026"

3. Smart Query Generation

Generates optimized SQL queries with:

Metric formulas: Aggregations over relevant data columns
Timeframe clauses: Automatically builds date range filters
Context filtering: Applies appropriate filters based on context
Comparison logic: Builds side-by-side period comparisons

4. Executive Summary Generation

Produces natural language summaries:

Summary for revenue analysis – GGR: $1,234,567.89.
Key recommendations: Investigate drivers behind GGR to sustain or improve performance.

API Contract

Primary Method

async analyzeBusinessQuestion(
  query: string,
  context?: BusinessContext,
  options?: BusinessInsightOptions
): Promise<BusinessInsight>

Input Types

interface BusinessContext {
  brand?: string;      // e.g., "brand-a"
  userId?: string;     // For audit trail
  dateRange?: {        // Optional override
    start: Date;
    end: Date;
  };
}

interface BusinessInsightOptions {
  forceNoData?: boolean;  // Test mode: skip data fetching
}

Output Structure

interface BusinessInsight {
  executive_summary: string;
  key_metrics: FormattedMetric[];
  insights: KeyFinding[];
  recommendations: string[];
  visualizations: Visualization[];
  natural_language_response: string;
  metadata: {
    executionTime: number;
    confidence: number;
    dataSources: string[];
  };
  raw_data: AnalyticalResult[];
}