Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.kaireonai.com/llms.txt

Use this file to discover all available pages before exploring further.

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 105 platform capabilities as AI tools for use from Claude Code, Cursor, and other MCP-compatible IDEs. The AI Assistant provides 130+ tools with guided autonomy for in-app natural language control.

​
Technology Stack

ComponentTechnologyVersionWhy
RuntimeNode.js22+Native ESM, stable async hooks, LTS performance
FrameworkNext.js (App Router)16.xUnified UI and API in one deployable, Turbopack dev speed
LanguageTypeScript (strict)5.9Type safety across frontend, API, and domain layers
UI LibraryReact19.xComponent model, concurrent features, Server Components
StylingTailwind CSS3.xUtility-first, consistent dark theme, small bundle
Server StateTanStack React Query5.xCache invalidation, optimistic updates, request deduplication
Client StateZustand5.xMinimal store for UI-only state (panels, selections)
ORMPrisma 7 with @prisma/adapter-pg7.xType-safe queries, driver adapter for connection pooling
DatabasePostgreSQL15+Relational integrity, JSON columns, DDL for dynamic schemas
Cache / Rate LimitRedis (via ioredis)—Enrichment cache, sliding-window rate limiting, session store
ValidationZod4.xRuntime schema validation shared between client and API
Flow EditorReact Flow (@xyflow/react)12.xVisual pipeline and Decision Flow editors
Job QueueBullMQ5.xDurable async jobs backed by Redis
AI SDKVercel AI SDK (multi-provider)6.xAnthropic, OpenAI, Google, Bedrock provider abstraction
AuthNextAuth.js5 betaSession-based auth with Prisma adapter, SAML support
Metricsprom-client15.xPrometheus-format metrics for operations dashboards
ChartsRecharts3.xComposable chart components for dashboards
TestingVitest + Playwright4.x / 1.xUnit tests (Vitest), E2E browser tests (Playwright)

​
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.
ModuleScopeKey Capabilities
Data/data/*Connectors, Schemas (real DDL), Pipelines (visual ETL with 11 transform types), Segments
Studio/studio/*Decision Flows, Business Hierarchy, Offers, Creatives, Channels, Contact Policies, Qualification Rules, Portfolio Optimization, Journeys, Triggers, Simulation
Algorithms/algorithms/*Scoring Models, Experiments with holdout groups and uplift calculation
AI/ai/*AI-powered Insights, Policy Recommendations, Segment Discovery, Content Intelligence
Dashboards/dashboards/*Operations (pipeline metrics, DLQ, circuit breakers), Business KPIs, Data Health, Model Health, Attribution
Settings/settings/*Tenant configuration, Integrations, API Explorer, Approval workflows, Appearance, AI configuration
Runs/runsPipeline and flow execution history
Each module follows the same file structure: 
domain/<module>.ts          # Zod schemas and TypeScript types
lib/api/<module>-client.ts  # Typed fetch functions
lib/api/<module>-hooks.ts   # React Query hooks (queries + mutations)
app/<module>/*              # Pages and layouts
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 24 registered source types (17 production-ready, 7 coming-soon): 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 11 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: qualification rules, 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:
EndpointPurpose
POST /api/v1/recommendExecute a Decision Flow and return ranked offers with computed values
POST /api/v1/respondRecord an outcome event (impression, click, conversion) with attribution
CRUD /api/v1/decision-flowsManage Decision Flow configurations
CRUD /api/v1/schemasManage entity schemas (triggers real DDL)
CRUD /api/v1/connectorsManage data source connections
CRUD /api/v1/pipelinesManage ETL pipeline definitions
GET /api/metricsPrometheus-format platform metrics

​
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.