Axoniq Insights Architecture

Overview

Axoniq Insights is an analytics and monitoring platform designed to provide deep insights into event-driven applications built with Axon Framework and Axon Server. From a user perspective, it serves as a powerful tool for analyzing event data, monitoring system behavior, and gaining actionable intelligence from your event streams.

Insights acts as a bridge between your Axon Server instances and various analytics tools, providing multiple interfaces for data access and analysis.

Core components

Event collection and storage

At its core, Insights connects to one or more Axon Server contexts to collect event data in real-time. Events flowing through your Axon Server contexts are automatically captured and stored in an optimized analytics database (DuckDB), referred to as the EventLake.

What this means for you:

  • Events from all your applications are automatically collected without requiring changes to your code

  • Historical event data is preserved for analysis and reporting

  • Data is stored in a columnar format optimized for analytical queries

  • Each Axon Server context maps to its own analytics database for isolation and performance

Web-based user interface

Insights provides a modern, responsive web interface that allows you to:

  • Visualize event data through interactive dashboards and charts

  • Execute SQL queries against your event data

  • Monitor system health and performance metrics

  • Configure connections to Axon Server instances

  • Manage user access and permissions

Access: The web UI is accessible via your browser at the configured server address (default: http://localhost:8080)

SQL query interface (PostgreSQL wire protocol)

One of the most powerful features is the ability to query your event data using standard SQL. Insights implements the PostgreSQL wire protocol, which means you can connect to it using any PostgreSQL-compatible client or tool.

What this enables:

  • Connect using familiar tools like DBeaver, pgAdmin, or DataGrip

  • Use your favorite programming language’s PostgreSQL driver

  • Build custom dashboards in tools like Grafana, Metabase, or Tableau

  • Write standard SQL queries to analyze event patterns and trends

  • Join event data with other data sources in your analytics pipeline

Connection details:

  • The database name in your connection string corresponds to the Axon Server context name

  • Authentication is integrated with the Insights' security model

  • Default port: configurable (typically 5432 for PostgreSQL compatibility)

AI-powered analytics

Insights includes built-in AI capabilities powered by large language models (Claude, GPT, or Mistral). This allows you to:

  • Ask natural language questions about your event data

  • Automatically generate SQL queries from plain English descriptions

  • Get intelligent insights and recommendations about your system’s behavior

  • Use conversational interfaces to explore your data

AI Features:

  • Model Context Protocol (MCP) Server: Exposes analytics capabilities as tools that AI agents can use

  • WebSocket-based Chat Interface: Real-time conversational analytics

  • Schema Analysis: AI understands your event structure and can suggest relevant queries

  • Query Generation: Automatically converts natural language to SQL

  • Query Execution: AI can execute queries and interpret results for you

Security and authentication

Insights provides flexible authentication and authorization options:

  • OAuth2 Integration: Support for Google, Keycloak, and other OAuth2 providers

  • Role-Based Access Control: Fine-grained permissions for different users

  • Context-Level Security: Control which Axon Server contexts users can access

  • Token-Based Authentication: For programmatic access and integrations

Data flow architecture

From a user perspective, here’s how data flows through the system:

  1. Collection Phase:

    • Your applications publish events to Axon Server

    • Insights subscribes to these event streams

    • Events are captured in real-time as they flow through the system

  2. Storage Phase:

    • Events are transformed and stored in the EventLake (DuckDB)

    • Data is organized by Axon Server context for efficient querying

    • Indexes and optimizations are applied automatically

  3. Access Phase:

    • You query data via the Web UI, SQL interface, or AI chat

    • Queries are executed against the DuckDB analytics database

    • Results are formatted and returned in the appropriate format

  4. Analysis Phase:

    • Visualize trends and patterns in your event data

    • Monitor system health and performance

    • Generate reports and alerts based on event patterns

    • Use AI to discover insights you might have missed

Integration points

Insights integrates with your ecosystem through several channels:

Axon Server connection

  • Connects to Axon Server using the native Java connector

  • Automatically discovers contexts and subscribes to event streams

  • Token-based authentication with Axon Server

Axoniq Platform integration

  • Optional integration with Axoniq Platform for centralized management

  • Centralized management of AI tokens

External analytics tools

  • PostgreSQL protocol compatibility allows connection from virtually any SQL tool

  • REST APIs for custom integrations

  • WebSocket endpoints for real-time data streaming

  • MCP server for AI agent integration

Deployment architecture

Insights is deployed as a single, self-contained Spring Boot application that includes:

  • Backend Services: REST APIs, WebSocket handlers, SQL query engine

  • PostgreSQL Wire Server: Accepts SQL client connections

  • Web Frontend: Served directly from the application

  • Embedded Databases:

    • SQLite for application metadata and configuration

    • DuckDB instances for event analytics (one per context)

Deployment Considerations:

  • Can run on-premises or in the cloud

  • Minimal resource requirements for small deployments

  • Scales vertically for larger event volumes

  • Data stored in configurable directory locations

  • No external database dependencies required (though supported)

Use cases

From a user perspective, Insights enables several key use cases:

  • Event Stream Analysis: Understand what events are flowing through your system and when

  • Performance Monitoring: Track command processing times, event publishing rates, and system throughput

  • Debugging and Troubleshooting: Query historical events to understand what happened during an incident

  • Business Intelligence: Extract business metrics from your event data

  • Compliance and Audit: Maintain queryable records of all system events

  • AI-Assisted Investigation: Use natural language to explore and understand your data

Getting started

To use Insights effectively:

  1. Deploy the Server: Install and configure Insights with connection details to your Axon Server

  2. Access the Web UI: Open your browser and log in to start exploring your data

  3. Connect SQL Tools: Configure your favorite SQL client to connect via the PostgreSQL protocol

  4. Run Queries: Start analyzing your event data using SQL or natural language

  5. Build Dashboards: Create visualizations and reports based on your event data