> ## 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. # Architecture Overview > System architecture, technology choices, and module structure of the KaireonAI platform. 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 ```mermaid theme={null} graph TB Client["Browser / API Client"] --> App["Next.js App Router"] App --> UI["UI Layer
React 19 · Tailwind CSS · React Flow"] App --> API["API Routes
/api/v1/*"] API --> Decision["Decision Engine"] API --> Pipeline["Pipeline Engine"] API --> MCP["MCP Server
170+ tools"] API --> AI["AI Assistant
70+ tools"] subgraph decision ["Decision Flow"] direction LR Qualify["Qualify"] --> Score["Score"] Score --> Rank["Rank"] Rank --> Arbitrate["Arbitrate"] end Decision --> Qualify subgraph pipeline ["Data Pipeline"] direction LR Source["Source
S3 · GCS · Azure · SFTP"] --> Transform["Transform
19 types"] Transform --> Target["Target
Schema tables"] end Pipeline --> Source API --> DB["PostgreSQL
Prisma 7"] API --> Cache["Redis
Cache · Queue · Events"] style Client fill:#3b82f6,color:#fff style App fill:#6366f1,color:#fff style Decision fill:#8b5cf6,color:#fff style Pipeline fill:#8b5cf6,color:#fff style MCP fill:#6366f1,color:#fff style AI fill:#6366f1,color:#fff style DB fill:#f59e0b,color:#000 style Cache fill:#f59e0b,color:#000 style decision fill:#1e1b4b,stroke:#6366f1,color:#e0e7ff style pipeline fill:#1e1b4b,stroke:#6366f1,color:#e0e7ff ``` 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](/self-host/architecture/scaling). ## Technology Stack | Component | Technology | Version | Why | | ---------------------- | ---------------------------------- | --------- | ----------------------------------------------------------------- | | **Runtime** | Node.js | 22+ | Native ESM, stable async hooks, LTS performance | | **Framework** | Next.js (App Router) | 16.x | Unified UI and API in one deployable, Turbopack dev speed | | **Language** | TypeScript (strict) | 5.9 | Type safety across frontend, API, and domain layers | | **UI Library** | React | 19.x | Component model, concurrent features, Server Components | | **Styling** | Tailwind CSS | 3.x | Utility-first, consistent dark theme, small bundle | | **Server State** | TanStack React Query | 5.x | Cache invalidation, optimistic updates, request deduplication | | **Client State** | Zustand | 5.x | Minimal store for UI-only state (panels, selections) | | **ORM** | Prisma 7 with `@prisma/adapter-pg` | 7.x | Type-safe queries, driver adapter for connection pooling | | **Database** | PostgreSQL | 15+ | Relational integrity, JSON columns, DDL for dynamic schemas | | **Cache / Rate Limit** | Redis (via ioredis) | -- | Enrichment cache, sliding-window rate limiting, session store | | **Validation** | Zod | 4.x | Runtime schema validation shared between client and API | | **Flow Editor** | React Flow (@xyflow/react) | 12.x | Visual pipeline and Decision Flow editors | | **Job Queue** | BullMQ | 5.x | Durable async jobs backed by Redis | | **AI SDK** | Vercel AI SDK (multi-provider) | 6.x | Anthropic, OpenAI, Google, Bedrock provider abstraction | | **Auth** | NextAuth.js | 5 beta | Session-based auth with Prisma adapter, OIDC SSO; SAML on roadmap | | **Metrics** | prom-client | 15.x | Prometheus-format metrics for operations dashboards | | **Charts** | Recharts | 3.x | Composable chart components for dashboards | | **Testing** | Vitest + Playwright | 4.x / 1.x | Unit 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. | Module | Scope | Key Capabilities | | -------------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | | **Data** | `/data/*` | Connectors, Schemas (real DDL), Pipelines (visual ETL with 19 built-in transform types), Segments | | **Studio** | `/studio/*` | Decision Flows, Business Hierarchy, Offers, Creatives, Channels, Contact Policies, Decisioning Gates, 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** | `/runs` | Pipeline and flow execution history | Each module follows the same file structure: ``` domain/.ts # Zod schemas and TypeScript types lib/api/-client.ts # Typed fetch functions lib/api/-hooks.ts # React Query hooks (queries + mutations) app//* # 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: ```mermaid theme={null} graph LR C["Connectors
(S3, Kafka, Snowflake, ...)"] --> S["Schemas
(DDL tables)"] S --> P["Pipelines
(visual ETL)"] P --> E["Enrichment
(customer data lookup)"] E --> D["Decision Engine
(score, rank, arbitrate)"] D --> R["API Response
(personalized offers)"] style C fill:#1e3a5f,stroke:#60a5fa,color:#bfdbfe style S fill:#1e3a5f,stroke:#60a5fa,color:#bfdbfe style P fill:#1e3a5f,stroke:#60a5fa,color:#bfdbfe style E fill:#312e81,stroke:#818cf8,color:#c7d2fe style D fill:#312e81,stroke:#818cf8,color:#c7d2fe style R fill:#312e81,stroke:#818cf8,color:#c7d2fe ``` 1. **Connectors** ingest data from 80+ registered source types: S3, Snowflake, BigQuery, PostgreSQL, MySQL, Kafka/Confluent (batch polling), REST APIs, and more. See [Connectors](/api-reference/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: | Endpoint | Purpose | | ----------------------------- | ------------------------------------------------------------------------ | | `POST /api/v1/recommend` | Execute a Decision Flow and return ranked offers with computed values | | `POST /api/v1/respond` | Record an outcome event (impression, click, conversion) with attribution | | `CRUD /api/v1/decision-flows` | Manage Decision Flow configurations | | `CRUD /api/v1/schemas` | Manage entity schemas (triggers real DDL) | | `CRUD /api/v1/connectors` | Manage data source connections | | `CRUD /api/v1/pipelines` | Manage ETL pipeline definitions | | `GET /api/metrics` | Prometheus-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`. ## Related How the Decision Flow engine processes recommend requests. Metrics, tracing, circuit breakers, and dead-letter queues. Connection pooling, caching, and horizontal scaling patterns. Local, App Runner, and Kubernetes deployment methods.