Skip to main content
KaireonAI is a monolithic Next.js application that serves both the platform UI and a RESTful API layer from a single deployment artifact. This architecture keeps operational complexity low — one container, one build, one deploy — while maintaining strict module boundaries internally through isolated domain types, API clients, and React Query hooks per feature area.

​
Architecture Diagram

The MCP server exposes 170+ platform capabilities as AI tools for use from Claude Code, Cursor, and other MCP-compatible IDEs. The AI Assistant provides 70+ tools with guided autonomy for in-app natural language control.

​
Process Model

By default the platform runs as a single container. On server startup (src/instrumentation.ts) the Next.js process also hosts, in-process:
  • an in-process BullMQ worker (DSAR, retrains, journeys, seeds, batch jobs),
  • an outbox poller that drains pending outbox_events,
  • the internal Flow scheduler that fires due pipelines (schedule + file-arrival triggers) without external cron, and
  • the maintenance scheduler that self-invokes the /api/** cron routes (retention cleanup, DSAR purge, DLQ drain, staging janitor, …).
This means a single-node deployment needs no separate worker, cron, or scheduler infrastructure. To split background work onto dedicated pods for horizontal scale, set WORKER_INPROCESS=0 on the API container and run standalone worker and outbox-publisher processes. The internal Flow scheduler is multi-replica safe via a PostgreSQL advisory lock (disable with FLOW_INTERNAL_SCHEDULER_ENABLED=false); the maintenance scheduler assumes a single replica (disable with MAINTENANCE_SCHEDULER_ENABLED=false and use external cron for multi-replica) — see the Scaling Guide.

​
Technology Stack

​
Module Architecture

The platform is organized into seven top-level modules. Each module owns its domain types, API client, and React Query hooks to enable parallel development without merge conflicts. Each module follows the same file structure:
Barrel files (domain/types.ts, lib/api/client.ts, lib/api/hooks.ts) re-export everything for backward compatibility with older imports.

​
Data Flow

The platform’s data pipeline moves information from external sources through transformation and enrichment into real-time decisioning:
  1. Connectors ingest data from 80+ registered source types: S3, Snowflake, BigQuery, PostgreSQL, MySQL, Kafka/Confluent (batch polling), REST APIs, and more. See Connectors for the full status table.
  2. Schemas define entity structures (customer, account, product) and create real PostgreSQL tables via DDL.
  3. Pipelines transform and load data using a visual flow editor with 19 built-in transform types (cast, filter, expression, hash, mask PII, rename, and others).
  4. Enrichment queries schema tables at decision time to load customer context, with Redis caching for performance.
  5. Decision Engine runs the configured flow: decisioning gates, formula-based computed values, scoring models, ranking, and multi-objective portfolio optimization.
  6. API Response returns personalized offer recommendations with computed values merged into the response payload.

​
API Layer

All API endpoints live under /api/v1/* and follow a consistent pattern:
  • Validation — Every request body is validated against a Zod schema before processing. Invalid requests return 400 with structured error details.
  • ORM — Prisma 7 with the @prisma/adapter-pg driver adapter handles all database access. The PrismaClient singleton uses a pg.Pool with configurable connection limits, timeouts, and graceful shutdown hooks.
  • Tenant Isolation — Queries are scoped to the authenticated tenant. Tenant settings control feature flags like decision tracing sample rates.
  • Error Handling — Standard HTTP status codes (200, 201, 400, 404, 409, 500) with JSON error bodies.
  • Rate Limiting — Sliding-window rate limiter protects high-throughput endpoints (journey callbacks, recommend API).
Key API routes:

​
Frontend Architecture

The frontend uses the Next.js App Router with a consistent two-panel layout: a list view on the left and a detail/editor panel on the right.
  • React Query manages all server state. Mutations automatically invalidate related queries so lists stay current after creates, updates, or deletes.
  • Zustand holds ephemeral UI state (selected items, panel visibility, editor mode) that does not need to survive a page reload.
  • React Flow (@xyflow/react) powers the visual editors for data pipelines, Decision Flows, and customer journeys. Nodes and edges are persisted as JSON in the database.
  • Component Library — Radix UI primitives with Tailwind styling. The theme uses oklch CSS variables with light, dark, and system modes.
  • Formula Engine — A custom tokenizer and recursive-descent parser evaluates computed field formulas safely (no eval). Supports arithmetic, comparisons, ternary expressions, and functions like min, max, round, coalesce, and concat.

Decision Engine

How the Decision Flow engine processes recommend requests.

Operations & Monitoring

Metrics, tracing, circuit breakers, and dead-letter queues.

Scaling Guide

Connection pooling, caching, and horizontal scaling patterns.

Deployment Options

Local, App Runner, and Kubernetes deployment methods.