Business Intelligence Engine — Architecture

Version: v1.0.0 Date: 2026-01-22 Location: analytics-platform/src/core/business-intelligence.service.ts

---

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:

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: SUM(ggr), COUNT(DISTINCT player_id)
• Timeframe clauses: Automatically builds WHERE date BETWEEN ...
• Brand filtering: Applies site_id 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[];
}

---

Supported Metrics

---

Data Source Mapping

The engine intelligently selects tables based on metric category:

---

Integration Points

---

Configuration

# No dedicated flags - uses core JORVIS configuration
# Leverages existing brand/schema settings

---

Best Practices

1. Use for dashboards: Ideal for pre-built analytics dashboards
2. Combine with Graph: Use Graph for complex multi-step queries, BI Engine for quick analytics
3. Monitor cache: Check analytics-query cache hit rate for performance

---

Related Documentation

• GRAPH_ORCHESTRATOR.md
• MODULE_REGISTRY.md