> ## Documentation Index
> Fetch the complete documentation index at: https://docs.flowx.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# FlowX.AI architecture

> FlowX.AI is built on a layered microservices architecture with event-driven communication. This page covers the 23+ backend services, AI Platform, client SDKs, and infrastructure that make up the platform.

## Overview

FlowX.AI is an event-driven platform built on specialized microservices that communicate primarily through Apache Kafka. The architecture is organized into distinct layers, each responsible for a specific concern — from process execution and application lifecycle management to authorization, content delivery, and AI-powered automation.

All backend services are containerized and deployed on Kubernetes. Client applications connect through an API Gateway that handles OAuth2 token validation and request routing.

<Info>
  For detailed database-to-service mapping, storage types, and sizing guidance, see the [Data architecture](./data-architecture) page.
</Info>

***

## Architecture overview

<Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.9/flowx-architecture-5.9.svg)
</Frame>

The diagram above shows the main architectural layers and how they interact. Almost all inter-service communication flows through Kafka, while the Events Gateway pushes real-time updates to clients via Server-Sent Events (SSE).

<Tip>
  All Kafka topics follow a consistent naming convention: `ai.flowx.{service}.{action}.v1` (for example, `ai.flowx.core.trigger.advance.process.v1`).
</Tip>

***

## FlowX Designer

The **FlowX Designer** is a collaborative, no-code/full-code web application for building and managing processes, UIs, integrations, and other application components.

* **BPMN editor** — visual process designer built on Fabric.js canvas
* **UI designer** — drag-and-drop interface builder for web and mobile
* **Data model builder** — schema design and management
* **Integration designer UI** — visual workflow builder for external system connections
* **Script builder** — Monaco-based code editor for business rules (JavaScript, Python, MVEL, Groovy)
* **AI features** — embedded config-time agents, conversation system, command center
* **CMS, theme editor, access management** — content, branding, and permissions configuration

The Designer communicates with backend services through REST APIs, GraphQL, SSE, and WebSocket connections, all routed through the API Gateway.

<Tip>
  The Designer runs in the browser and is not deployed as part of the backend infrastructure. It connects to backend services through the API Gateway.
</Tip>

<Card title="FlowX Designer" href="../flowx-designer/overview" icon="pencil" />

***

## Core Engine layer

The Core Engine layer handles workflow execution, process orchestration, and real-time event delivery.

### Process Engine

The **Process Engine** is the central orchestration service that executes BPMN 2.0 process definitions and manages process instance lifecycles.

* Executes business processes and coordinates real-time interactions between users, systems, and data
* Manages process instances from creation through completion
* Supports multiple scripting languages: JavaScript (GraalJS), Python 3 (GraalPy), MVEL, and Groovy
* Dynamically generates and delivers UI components based on process state

**Data stores:** PostgreSQL or Oracle (`process_engine`), MongoDB (`app-runtime` read), Redis (cache), Elasticsearch (indexing)

<Card title="Process Engine" href="../platform-deep-dive/core-components/flowx-engine" icon="gears" />

### Advancing Controller

The **Advancing Controller** ensures efficient process instance progression, particularly in scaled deployments.

* Distributes workload evenly across Process Engine instances
* Facilitates redistribution during scale-up and scale-down
* Prevents process instances from getting stuck if a worker pod fails
* Performs cleanup tasks and monitors worker pod status

**Data stores:** PostgreSQL (`advancing`), Redis

<Card title="Advancing Controller" href="../platform-deep-dive/core-components/advancing-controller" icon="forward" />

### Events Gateway

The **Events Gateway** centralizes real-time communication between backend services and frontend clients through Server-Sent Events (SSE).

* Routes and distributes messages from Kafka topics to appropriate frontend clients
* Enables real-time UI updates without page refreshes or polling
* Uses Redis pub/sub to ensure messages reach the correct instance holding the SSE connection

<Card title="Events Gateway" href="../platform-deep-dive/core-components/events-gateway" icon="tower-broadcast" />

### Scheduler Core

The **Scheduler Core** handles time-based operations within processes.

* Sets process expiration dates and reminders
* Triggers time-based events and activities
* Manages recurring tasks and delayed actions

**Data stores:** MongoDB (`notification` shared with Notification Plugin)

<Card title="Scheduler Core" href="../platform-deep-dive/core-extensions/scheduler" icon="clock" />

***

## Application Lifecycle layer

The Application Lifecycle layer manages the full journey from design through build to deployment.

### Application Manager

The **Application Manager** handles project lifecycle management.

* Creates, updates, and deletes projects and their resources
* Manages versions, manifests, and configurations
* Serves as a proxy for frontend resource requests
* Handles project builds and deployments

**Data stores:** PostgreSQL (`app_manager`), MongoDB (`app-runtime`), S3 (`applications-bucket`)

<Card title="Projects" href="../projects" icon="folder-open" />

### Runtime Manager

The **Runtime Manager** works alongside the Application Manager to deploy and manage applications in runtime environments.

* Deploys application builds to runtime environments
* Manages runtime configurations and environment-specific settings
* Monitors and manages active application instances

### Admin

The **Admin** service manages process definitions and platform-wide settings.

* Stores and edits process definitions and data models
* Manages user roles and permissions
* Configures system-wide settings

**Data stores:** PostgreSQL (`flowxadmin`), MongoDB (`data-model`)

### Data Sync

The **Data Sync** job coordinates database migrations and data synchronization across multiple services.

* Manages Liquibase migrations for `app_manager`, `auth_system`, and `process_engine` databases
* Synchronizes resource definitions across MongoDB instances (CMS, Scheduler, Task Management, Document Plugin, Notification Plugin, Integration Designer)

***

## Content & Data layer

The Content & Data layer handles taxonomies, search, data persistence, and external system integrations.

### CMS Core

The **CMS Core** (Content Management System) manages all taxonomies and structured content within the platform.

* Manages enumerations, dropdown options, and categories
* Stores and serves localization content and translations
* Organizes media assets and reference data

**Data stores:** MongoDB (`cms-core`), S3 (`media-library-bucket`, `cms-private-storage-bucket`)

<Card title="Content Management" href="../platform-deep-dive/core-extensions/content-management/content-management" icon="folder-grid" />

### Data Search

The **Data Search** service enables search capabilities across process instances using Elasticsearch.

* Indexes process data automatically on status changes or at configured trigger points
* Supports filtering by process status, date ranges, and indexed keys
* Enables cross-application data discovery

**Data stores:** Elasticsearch (process instance index)

<Card title="Data Search" href="../platform-deep-dive/core-extensions/search-data-service" icon="magnifying-glass" />

### NoSQL DB Runner

The **NoSQL DB Runner** powers the FlowX Database feature, which stores structured data independently of process instances.

* Executes MongoDB operations (find, insert, update, delete)
* Supports both native MongoDB and Azure Cosmos DB (MongoDB API)
* Enables data sharing between different process instances

**Data stores:** MongoDB (`nosql-db-runner`)

<Card title="FlowX Database" href="../platform-deep-dive/integrations/flowx-database" icon="database" />

### Integration Designer

The **Integration Designer** provides a visual interface for creating and managing integrations with external systems.

* Defines REST API endpoints and authentication methods
* Creates and configures integration workflows with parallel branches
* Maps data between FlowX.AI processes and external systems
* Supports AI nodes for text, document, image, and data processing

**Data stores:** MongoDB (`integration-designer`), S3 (`workflows-bucket`)

<Card title="Integration Designer" href="../platform-deep-dive/integrations/integration-designer" icon="ruler-combined" />

***

## Authorization & Security layer

The Authorization & Security layer provides multi-tenant access control, workspace isolation, and identity management.

### Authorization System

The **Authorization System** is the centralized authorization service for the platform.

* Manages workspaces, users, groups, roles, and permissions
* Enforces access control lists (ACLs) for fine-grained resource permissions
* Provides RBAC (role-based access control) at organization, workspace, and project levels

**Data stores:** PostgreSQL (`auth_system`), SpiceDB (ACL operations)

### SpiceDB

**SpiceDB** is an embedded relationship-based access control (ReBAC) engine inspired by Google's Zanzibar paper.

* Stores and evaluates authorization policies
* Provides consistent, fine-grained permission decisions across all platform services
* Supports reverse lookups (finding all resources a user can access)

<Info>
  SpiceDB is an embedded component shipped with the platform. It runs alongside other services and is not deployed separately.
</Info>

### Organization Manager

The **Organization Manager** handles organization and tenant lifecycle management.

* Manages organization creation and provisioning
* Handles user registration and onboarding
* Monitors platform component health
* Publishes organization lifecycle events to Kafka

**Data stores:** PostgreSQL (`org_manager`)

### Multi-tenancy and workspaces

FlowX.AI uses **workspaces** to provide logical data isolation across the platform. Each workspace operates independently with its own resources (projects, libraries, themes) and access controls. The Authorization System, SpiceDB, and Organization Manager work together to enforce tenant boundaries while allowing users to belong to multiple workspaces.

<Card title="Workspaces" href="../projects/workspaces" icon="building" />

### Identity providers

FlowX.AI delegates authentication to external identity providers. Every request passes through the API Gateway, which validates OAuth2 tokens before allowing access.

<CardGroup cols={2}>
  <Card title="Keycloak" href="../../setup-guides/access-management/configuring-an-iam-solution" icon="key" />

  <Card title="Azure AD (Entra)" href="../../setup-guides/access-management/configuring-an-iam-solution-entra" icon="key" />
</CardGroup>

***

## Business services

Business services extend the core engine with domain-specific capabilities. Document, Notification, and Task Management are deployed as core backend services alongside the engine; OCR and Reporting are formal plugins that ship through the Plugins versioning track.

### Document

Handles document generation and management.

* Generates documents from HTML templates
* Supports file upload, conversion, splitting, combining, and encryption/decryption
* Manages document storage and retrieval

**Data stores:** PostgreSQL (`document`), MongoDB (`document`, `app-runtime` read), S3 (`flowx-dev-bucket`, `temp-bucket`)

### Notification

Manages notifications across multiple channels.

* Sends email, SMS, and push notifications
* Handles OTP (one-time password) generation and validation
* Supports notification templates with dynamic content substitution

**Data stores:** MongoDB (`notification`, `app-runtime` read), S3 (`flowx-dev`)

### Task Management

Handles human task assignment and lifecycle.

* Manages task creation, assignment, and completion
* Supports allocation rules and out-of-office delegation
* Provides multi-language localization with substitution tags

**Data stores:** PostgreSQL (`process_engine` shared), MongoDB (`task-management-plugin`, `app-runtime` read)

<Card title="Task Management" href="../platform-deep-dive/core-extensions/task-management/task-management-overview" icon="list-check" />

### OCR (plugin)

The **OCR Plugin** provides optical character recognition for document processing and data extraction.

### Reporting (plugin)

The **Reporting Plugin** powers analytics and dashboards, integrating with Apache Superset for visualization.

<Card title="Plugins" href="../platform-deep-dive/plugins/custom-plugins" icon="plug" />

***

## Supporting Services

Supporting services provide cross-cutting capabilities like auditing, email communication, and licensing.

### Audit Core

The **Audit Core** service provides a centralized audit trail for all platform activities.

* Logs user actions and system events with timestamps, subjects, and status
* Stores audit data in Elasticsearch for efficient querying
* Ingests events from Kafka topic `ai.flowx.core.trigger.save.audit.v1`

**Data stores:** Elasticsearch (audit index)

<Card title="Audit" href="../platform-deep-dive/core-extensions/audit" icon="clipboard-list" />

### Email Gateway

The **Email Gateway** handles email communication workflows.

* Sends emails via SMTP and receives emails via IMAP
* Monitors configured mailboxes and publishes incoming email events to Kafka for process triggering
* Supports leader election for high availability across distributed instances

**Data stores:** PostgreSQL (`email_gateway`), MongoDB (`app-runtime` read)

### File Gateway

The **File Gateway** handles file-transfer integrations with external storage systems.

* Connects to FTP, SFTP, S3, and Azure Blob storage to ingest files into workflows and deliver generated artifacts back
* Polls watched locations for new files, uploads them to the Document service, and publishes Kafka events to start processes (file triggers)
* Supports distributed leasing for high availability across instances, mirroring the Email Gateway

**Data stores:** MongoDB (`file-gateway` collections, `app-runtime` read)

### AI Gateway

The **AI Gateway** powers the AI chat experience in the FlowX Designer.

* Streams AI assistant responses to the Designer in real time via Server-Sent Events (SSE)
* Routes chat requests to the config-time agents and manages conversation context
* Enforces workspace-level access control on AI interactions

**Data stores:** MongoDB, SpiceDB (ACL operations)

### License

The **License** service (formerly known as the License Engine) manages platform and application licensing, subscription plans, feature quotas, and usage tracking for FlowX organizations across SaaS and self-hosted deployments.

For setup and configuration, see [License service setup](/5.9/setup-guides/license-engine-setup).

**Data stores:** PostgreSQL (`license`)

***

## AI Platform

The **AI Platform** extends FlowX.AI with intelligent agents that operate at two levels:

* **Config-time agents** — embedded in the FlowX Designer to help developers and analysts build apps faster (AI Analyst, AI Designer, AI Developer, AI Assistant)
* **Business agents** — power end-user experiences at runtime, built with the Agent Builder or installed from the Agentic Apps Marketplace

In 5.9.0, the AI Platform comprises 10 services — `di-platform`, `ai-platform-ai-developer`, `ai-platform-planner`, `ai-platform-ai-analyst`, `ai-platform-ai-designer`, `ai-platform-agent-builder`, `ai-platform-ai-assistant`, `embedder`, `knowledgebase-rag`, and `knowledgebase-indexer-v2` — plus the **Observatory** stack (`observatory-api`, `observatory-web`, `observatory-guards`) for AI observability and governance. Vector storage and retrieval are handled by **Qdrant** (embedded).

### Standalone AI services

A separate set of AI-adjacent services ships from their own repositories rather than the AI Platform monorepo. They are not part of the AI Platform umbrella and install via separate paths:

* **doc-parser** — document parsing engine (PDF, DOCX, XLSX, PPTX, images; supports Tesseract, RapidOCR, EasyOCR; semantic chunking for RAG; signature detection; table extraction)
* **doc-converter** — document format conversion
* **web-crawler** — web content ingestion for the Web Page Extractor node
* **data-privacy** — PII detection and redaction (PII Guard)
* **speech-to-text** — audio transcription for voice and call workflows
* **evals-judge** — LLM-as-judge evaluation service for scoring agent and model outputs
* **modpod** — supporting runtime service

<Card title="AI Platform" href="../../ai-platform/ai-in-flowx" icon="hand-sparkles" />

***

## Client SDKs

The FlowX.AI SDKs provide process renderers that display dynamic UIs and orchestrate user interactions on each platform. The SDK architecture uses a framework-agnostic core (`@flowx/core-sdk`) with platform-specific wrappers.

<CardGroup cols={2}>
  <Card title="Angular SDK" icon="code" href="../../sdks/angular-renderer">
    `@flowx/angular-sdk` for Angular applications
  </Card>

  <Card title="React SDK" icon="code" href="../../sdks/react-renderer">
    `@flowx/react-sdk` for React applications
  </Card>

  <Card title="React Native SDK" icon="code" href="../../sdks/react-native-renderer">
    Renderer for React Native applications
  </Card>

  <Card title="iOS SDK" icon="apple" href="../../sdks/ios-renderer">
    Native iOS renderer
  </Card>

  <Card title="Android SDK" icon="robot" href="../../sdks/android-renderer">
    Native Android renderer
  </Card>
</CardGroup>

<Note>
  The SDKs include companion packages for theming (`@flowx/ui-theme`) and UI components (`@flowx/ui-toolkit`).
</Note>

***

## Service communication

The following diagram shows the typical request flow through the platform:

```mermaid theme={"system"}
sequenceDiagram
    participant Client as Client app (SDK)
    participant GW as API Gateway
    participant Engine as Process Engine
    participant Kafka as Kafka
    participant Plugin as Plugin / Integration
    participant Events as Events Gateway

    Client->>GW: Start process (REST + OAuth2 token)
    GW->>Engine: Forward authenticated request
    Engine->>Kafka: Publish process event
    Kafka->>Plugin: Route to plugin or integration
    Plugin->>Kafka: Return result event
    Kafka->>Engine: Deliver result
    Engine->>Kafka: Publish UI update event
    Kafka->>Events: Route SSE event
    Events->>Client: Push real-time update (SSE)
```

1. **Client applications** initiate processes through the API Gateway using REST calls with an OAuth2 token
2. The **Process Engine** executes the process definition and publishes events to Kafka
3. **Plugins and integrations** consume events, perform their work, and publish results back to Kafka
4. The **Events Gateway** picks up UI update events and pushes them to connected clients via SSE

This event-driven approach enables the platform to handle long-running processes asynchronously, keeping the user experience responsive while external systems process requests in the background.

***

## Service quick reference

| Service                       | Layer           | Port  | Primary DB          | Key Dependencies                    |
| ----------------------------- | --------------- | ----- | ------------------- | ----------------------------------- |
| **Process Engine**            | Core Engine     | 8085  | PostgreSQL, MongoDB | Kafka, Redis, Elasticsearch         |
| **Advancing Controller**      | Core Engine     | 8097  | PostgreSQL          | Redis, Process Engine               |
| **Events Gateway**            | Core Engine     | 8090  | —                   | Redis, Kafka                        |
| **Scheduler Core**            | Core Engine     | 8091  | MongoDB             | Kafka                               |
| **Application Manager**       | App Lifecycle   | 8099  | PostgreSQL, MongoDB | S3                                  |
| **Runtime Manager**           | App Lifecycle   | —     | —                   | Application Manager                 |
| **Admin**                     | App Lifecycle   | 8086  | PostgreSQL, MongoDB | —                                   |
| **Data Sync**                 | App Lifecycle   | —     | —                   | PostgreSQL (3 DBs), MongoDB (8 DBs) |
| **CMS Core**                  | Content & Data  | 8087  | MongoDB             | S3                                  |
| **Data Search**               | Content & Data  | 8096  | Elasticsearch       | Kafka                               |
| **NoSQL DB Runner**           | Content & Data  | 8121  | MongoDB             | —                                   |
| **Integration Designer**      | Content & Data  | 8098  | MongoDB             | S3                                  |
| **Authorization System**      | Auth & Security | 8100  | PostgreSQL          | SpiceDB                             |
| **SpiceDB**                   | Auth & Security | 50051 | (embedded)          | PostgreSQL                          |
| **Organization Manager**      | Auth & Security | 8102  | PostgreSQL          | SpiceDB                             |
| **Document Plugin**           | Plugins         | 8088  | PostgreSQL, MongoDB | S3                                  |
| **Notification Plugin**       | Plugins         | 8089  | MongoDB             | S3                                  |
| **Task Management**           | Plugins         | 8093  | PostgreSQL, MongoDB | —                                   |
| **OCR Plugin**                | Plugins         | —     | —                   | —                                   |
| **Audit Core**                | Supporting      | 8095  | Elasticsearch       | Kafka                               |
| **Email Gateway**             | Supporting      | —     | PostgreSQL, MongoDB | Kafka                               |
| **File Gateway**              | Supporting      | —     | MongoDB             | Kafka, Document                     |
| **AI Gateway**                | Supporting      | —     | MongoDB             | SpiceDB, AI Platform                |
| **License**                   | Supporting      | 8105  | PostgreSQL          | —                                   |
| **Document Parser**           | AI Platform     | —     | —                   | Kafka, AI providers                 |
| **AI Platform (10 services)** | AI Platform     | —     | Qdrant              | Kafka, AI providers                 |
| **FlowX Designer**            | Client          | —     | —                   | API Gateway                         |
| **Web / Mobile SDKs**         | Client          | —     | —                   | API Gateway, Events Gateway         |

<Tip>
  For detailed database names, S3 bucket names, and per-service operations (read/write), see the [Data architecture](./data-architecture) page.
</Tip>

***

## Infrastructure

FlowX.AI requires the following infrastructure components:

* **PostgreSQL / Oracle** — system of record for process definitions, instance state, and platform configuration
* **MongoDB** — document storage for runtime configuration, workflow state, and flexible data structures
* **Redis** — in-memory cache for process definitions, compiled scripts, and distributed locks
* **Apache Kafka** — event streaming backbone for all inter-service communication
* **Elasticsearch** — search indexes for process data and audit logs
* **S3-compatible storage** — files, documents, and binary assets
* **Qdrant** — vector database for the AI Platform RAG path (client-provisioned)

All services are containerized and designed for Kubernetes deployment. Stateless components support horizontal scaling, and Kafka provides resilient message handling across scaled instances.

<CardGroup cols={2}>
  <Card title="Data architecture" href="./data-architecture" icon="database">
    Database-to-service mapping and storage details
  </Card>

  <Card title="Third-party components" href="../platform-deep-dive/third-party-components" icon="cube">
    Supported versions and compatibility matrix
  </Card>
</CardGroup>

***

## Quick demo

<video controls src="https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/Introduction%20to%20FlowX.AI%20-%20Architecture%20Overview.mp4" />

***

## Related resources

<CardGroup cols={2}>
  <Card title="Data architecture" href="./data-architecture" icon="database">
    Database-to-service mapping, storage types, and sizing guidance
  </Card>

  <Card title="Third-party components" href="../platform-deep-dive/third-party-components" icon="cube">
    Supported versions and compatibility matrix
  </Card>

  <Card title="AI Platform" href="../../ai-platform/ai-in-flowx" icon="hand-sparkles">
    AI agents for config-time and runtime
  </Card>

  <Card title="SDKs overview" href="../../sdks/sdks-overview" icon="cubes">
    Web and mobile SDK documentation
  </Card>
</CardGroup>