> ## 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: services, layers, and data flow > Explore the FlowX.AI microservices architecture: core engine, app lifecycle, authorization, business services, AI Platform, SDKs, and infrastructure. ## 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 app 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. > [!NOTE] > > For detailed database-to-service mapping and storage types, see the [Data architecture](https://docs.flowx.ai/6.x/docs/platform-overview/data-architecture.md) page. *** ## Architecture overview ![FlowX.AI 5.9 platform architecture with services, layers, and data stores](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/flowx-architecture-5.9.svg) Almost all inter-service communication flows through Kafka, while the Events Gateway pushes real-time updates to clients via Server-Sent Events (SSE). > [!TIP] > > Most Kafka topics follow the naming convention `ai.flowx.{service}.{action}.v1` (for example, `ai.flowx.core.trigger.advance.process.v1`). Some, mainly AI Platform job topics such as `ai.flowx.web-crawler.job.request`, have no version suffix. ### Explore interactively Click a component to inspect its connections, use the guided views to walk the request and event paths, or [open the diagram full screen](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/flowx-architecture-5.9.html). [⛶ Open full screen](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/flowx-architecture-5.9.html) [Interactive FlowX.AI 5.9 platform architecture diagram](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/flowx-architecture-5.9.html) *** ## Service quick reference Looking up a specific database or dependency? Everything is in this table; the sections after it explain each layer and service in detail. All services listen on port 8080, with the management (actuator) port on 8081. SpiceDB serves gRPC on port 50051. | Service | Layer | Primary DB | Key Dependencies | | - | - | - | - | | **Process Engine** | Core Engine | PostgreSQL, MongoDB | Kafka, Redis, Elasticsearch, SpiceDB | | **Advancing Controller** | Core Engine | PostgreSQL | Process Engine | | **Events Gateway** | Core Engine | — | Redis, Kafka | | **Scheduler Core** | Core Engine | MongoDB | Kafka | | **Application Manager** | App Lifecycle | PostgreSQL, MongoDB | S3, SpiceDB | | **Runtime Manager** | App Lifecycle | PostgreSQL, MongoDB | Redis, Application Manager | | **Admin** | App Lifecycle | PostgreSQL, MongoDB | SpiceDB | | **Data Sync** | App Lifecycle | — | PostgreSQL (3 DBs), MongoDB (8 DBs) | | **CMS Core** | Content & Data | MongoDB | S3, SpiceDB | | **Data Search** | Content & Data | Elasticsearch | Kafka | | **NoSQL DB Runner** | Content & Data | MongoDB | — | | **Integration Designer** | Content & Data | MongoDB, PostgreSQL | S3, SpiceDB | | **Authorization System** | Auth & Security | PostgreSQL | SpiceDB | | **SpiceDB** | Auth & Security | (embedded) | PostgreSQL | | **Organization Manager** | Auth & Security | PostgreSQL | SpiceDB | | **Document Plugin** | Plugins | PostgreSQL, MongoDB | S3 | | **Notification Plugin** | Plugins | MongoDB | S3 | | **Task Management** | Plugins | PostgreSQL, MongoDB | SpiceDB | | **OCR Plugin** | Plugins | — | — | | **Audit Core** | Supporting | Elasticsearch | Kafka | | **Email Gateway** | Supporting | PostgreSQL, MongoDB | Kafka | | **File Gateway** | Supporting | MongoDB | Kafka, Document | | **Webhook Gateway** | Supporting | PostgreSQL | Kafka | | **AI Gateway** | Supporting | MongoDB | SpiceDB, AI Platform | | **License** | Supporting | PostgreSQL | — | | **Document Parser** | AI Platform | — | Kafka, AI providers | | **AI Platform (16 services)** | AI Platform | Qdrant | Kafka, AI providers | | **FlowX Designer** | Client | — | API Gateway | | **Web / Mobile SDKs** | Client | — | API Gateway, Events Gateway | > [!NOTE] > > **SpiceDB is a startup dependency for more services than it serves.** The Authorization System, Admin, AI Gateway, Application Manager, Audit Core, CMS Core, Document Plugin, Email Gateway, File Gateway, Integration Designer, Notification Plugin, Task Management, and Process Engine include `spicedb` in their readiness health group, so those pods do not become ready while SpiceDB is unreachable. This includes the Process Engine, which serves runtime traffic but also checks design-time permissions on the process instance and incident endpoints that FlowX Designer calls. > [!TIP] > > For detailed database names, S3 bucket names, and per-service operations (read/write), see the [Data architecture](https://docs.flowx.ai/6.x/docs/platform-overview/data-architecture.md) page. *** ## FlowX Designer The **FlowX Designer** is a collaborative, no-code/full-code web app for building and managing processes, UIs, integrations, and other app 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**: the [Developer Agentic Harness](https://docs.flowx.ai/6.x/ai-platform/developer-agentic-harness.md), opened from the agent rail, with its conversations * **CMS, theme editor, access management**: content, branding, and permissions configuration The Designer communicates with backend services through REST APIs, GraphQL, and SSE 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. > [card] [FlowX Designer](https://docs.flowx.ai/6.x/docs/flowx-designer/overview.md) *** ## 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 and Python 3 (run by the native script engine by default), MVEL, and Groovy. The GraalVM script engine is deprecated. FlowX.AI 6.1.x is the last release family that supports GraalVM as a script engine ([migration steps](https://docs.flowx.ai/release-notes/v6.x/v6.0.0-october-2026/migrating-from-v5.9-to-v6.0/migration-overview.md#move-scripts-off-the-graalvm-engine)). * Dynamically generates and delivers UI components based on process state **Data stores:** PostgreSQL or Oracle (`process_engine`, `advancing`), MongoDB (`app-runtime` read), Redis (cache), Elasticsearch (indexing) > [card] [Process Engine](https://docs.flowx.ai/6.x/docs/platform-deep-dive/core-components/flowx-engine.md) ### Advancing Controller The **Advancing Controller** ensures efficient process instance progression, particularly in scaled deployments. * Distributes workload evenly across Process Engine instances * Redistributes work 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`) > [card] [Advancing Controller](https://docs.flowx.ai/6.x/docs/platform-deep-dive/core-components/advancing-controller.md) ### 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 Streams to ensure messages reach the correct instance holding the SSE connection > [card] [Events Gateway](https://docs.flowx.ai/6.x/docs/platform-deep-dive/core-components/events-gateway.md) ### 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 (`scheduler-core`) > [card] [Scheduler Core](https://docs.flowx.ai/6.x/docs/platform-deep-dive/core-extensions/scheduler.md) *** ## 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] [Projects](https://docs.flowx.ai/6.x/docs/projects/managing-applications/application.md) ### Runtime Manager The **Runtime Manager** works alongside the Application Manager to deploy and manage apps in runtime environments. * Deploys app builds to runtime environments * Manages runtime configurations and environment-specific settings * Monitors and manages active app instances **Data stores:** PostgreSQL (`app_manager` shared), MongoDB (`app-runtime`), Redis (cache) ### 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 (`process_engine` shared), MongoDB (`data-model`) ### Data Sync The **Data Sync** job coordinates database migrations and data synchronization across multiple services. * Manages Liquibase migrations for `app_manager`, `authorization_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] [Content Management](https://docs.flowx.ai/6.x/docs/platform-deep-dive/core-extensions/content-management/content-management.md) ### 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-app data discovery **Data stores:** Elasticsearch (process instance index) > [card] [Data Search](https://docs.flowx.ai/6.x/docs/platform-deep-dive/core-extensions/search-data-service.md) ### 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] [FlowX Database](https://docs.flowx.ai/6.x/docs/platform-deep-dive/integrations/flowx-database.md) ### 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`), PostgreSQL or Oracle (`advancing`), S3 (`workflows-bucket`) > [card] [Integration Designer](https://docs.flowx.ai/6.x/docs/platform-deep-dive/integrations/integration-designer.md) *** ## 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 * Covers both designer users and runtime end users, through two separate decision engines **Data stores:** PostgreSQL (`authorization_system`), SpiceDB (design-time ACL operations) > [!NOTE] > > **Two decision engines, one service.** Designer users and runtime end users are both managed by the Authorization System, and both are stored in the `authorization_system` PostgreSQL database. What differs is how a permission decision is made: designer-time permissions are relationship tuples evaluated in SpiceDB, while runtime permissions are resolved from relational tables in the same PostgreSQL database. The two do not interact at runtime. ### SpiceDB **SpiceDB** is a relationship-based access control (ReBAC) engine inspired by Google's Zanzibar paper. * Stores and evaluates design-time authorization policies * Provides consistent, fine-grained permission decisions for Designer access checks * Supports reverse lookups (finding all resources a user can access) > [!NOTE] > > **Scope: design-time permissions only.** SpiceDB backs build-time access checks in the FlowX Designer (who can edit which workspace, project, or resource). Runtime permissions, meaning which end users can interact with which solution at execution time, use a separate custom implementation inside the Authorization System that does not call SpiceDB. See [Runtime authorization](https://docs.flowx.ai/6.x/setup-guides/access-management/runtime-authorization.md). > [!NOTE] > > SpiceDB ships with the platform rather than being sourced by the customer, but it runs as its own workload and is installed through the SpiceDB operator. See the [SpiceDB setup guide](https://docs.flowx.ai/6.x/setup-guides/spicedb.md) for the installation steps. ### 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] [Workspaces](https://docs.flowx.ai/6.x/docs/projects/workspaces.md) ### Identity providers FlowX.AI delegates authentication to external identity providers. Every request passes through the API Gateway, which validates OAuth2 tokens before allowing access. > [card] [Keycloak](https://docs.flowx.ai/6.x/setup-guides/access-management/configuring-an-iam-solution.md) > [card] [Azure AD (Entra)](https://docs.flowx.ai/6.x/setup-guides/access-management/configuring-an-iam-solution-entra.md) *** ## 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_plugin`), MongoDB (`document-plugin`, `app-runtime` read), S3 (`flowx-dev-bucket` prefix, `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-plugin`, `app-runtime` read), S3 (`qdevlocal-preview-paperflow` prefix) ### 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] [Task Management](https://docs.flowx.ai/6.x/docs/platform-deep-dive/core-extensions/task-management/task-management-overview.md) ### 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] [Plugins](https://docs.flowx.ai/6.x/docs/platform-deep-dive/plugins/custom-plugins.md) *** ## 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] [Audit](https://docs.flowx.ai/6.x/docs/platform-deep-dive/core-extensions/audit.md) ### Email Gateway The **Email Gateway** handles email communication workflows. * Receives emails via IMAP or Microsoft Graph * 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`) ### Webhook Gateway The **Webhook Gateway** receives inbound webhook calls from external systems and uses them to trigger FlowX processes. * Exposes a public, API-key-authenticated `/webhooks/**` endpoint that external systems call over HTTP * On a valid request, publishes Kafka events that the Process Engine consumes to start a new process instance or resume a waiting message-catch event * Producer-only to Kafka: it does not consume any topics * Requires ingress to be enabled, since it receives HTTP requests from outside the cluster **Data stores:** PostgreSQL (`webhook_gateway`) ### 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 app 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](https://docs.flowx.ai/6.x/setup-guides/license-engine-setup.md). **Data stores:** PostgreSQL (`license`) *** ## AI Platform The **AI Platform** extends FlowX.AI with intelligent agents that operate at two levels: * **Config-time agents**: the [Developer Agentic Harness](https://docs.flowx.ai/6.x/ai-platform/developer-agentic-harness.md) in the FlowX Designer, which helps developers and analysts build apps faster * **Business agents**: power end-user experiences at runtime, built with the Agent Builder or installed from the Agentic Apps Marketplace In 6.0, the AI services deploy with the `flowx-ai` Helm chart in three groups: base (`ai-gateway`, `doc-parser`, `embedder`, `knowledgebase-indexer-v2`, `knowledgebase-rag`), runtime (`agent-builder`, `data-privacy`, `doc-converter`, `dynamic-classifier`, `evals-judge`, `speech-to-text`, `web-crawler`, and the optional `cee-pii`), and dev-time (`ai-analyst`, `ai-architect`, `ai-assistant`, `ai-designer`, `ai-developer`, `harness`, `kb-enrichment`, `planner`, `ui-driver`). See [AI service groups in the Helm chart](https://docs.flowx.ai/release-notes/v6.x/v6.0.0-october-2026/deployment-guidelines-v6.0.md#ai-service-groups-in-the-helm-chart). [Observatory](https://docs.flowx.ai/6.x/observatory/overview.md), for AI observability and governance, is not part of these services: it deploys as its own stack, and agents report to it through the Observatory SDK. Vector storage and retrieval are handled by **Qdrant** (embedded). On 5.9.0 and 5.9.1, most of these services carry an `ai-platform-` name prefix (for example, `ai-platform-planner`), which 5.9.2 drops; `ai-architect` is available only starting with 5.9.2 and does not exist in earlier 5.9.x deployments. In 5.9.0 this tier shipped `di-platform`, which was decommissioned into `kb-enrichment` in 5.9.1. ### Document and utility AI services Six of the AI Platform services handle document processing, ingestion, transcription, and evaluation workloads. On 5.9.0 and 5.9.1 they installed via separate paths and versioned independently; in 6.x they deploy with the `flowx-ai` chart and version with it: * **doc-parser**: document parsing engine (PDF, DOCX, XLSX, PPTX, images; supports Tesseract and EasyOCR, plus RapidOCR up to 5.9.5; 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**, a supporting runtime service, remains standalone: it installs via its own path and versions on its own cadence. > [card] [AI Platform](https://docs.flowx.ai/6.x/ai-platform/ai-in-flowx.md) *** ## 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. > [card] [Angular SDK](https://docs.flowx.ai/6.x/sdks/angular-renderer.md) > > `@flowx/angular-sdk` for Angular applications > [card] [React SDK](https://docs.flowx.ai/6.x/sdks/react-renderer.md) > > `@flowx/react-sdk` for React applications > [card] [React Native SDK](https://docs.flowx.ai/6.x/sdks/react-native-renderer.md) > > Renderer for React Native applications > [card] [iOS SDK](https://docs.flowx.ai/6.x/sdks/ios-renderer.md) > > Native iOS renderer > [card] [Android SDK](https://docs.flowx.ai/6.x/sdks/android-renderer.md) > > Native Android renderer > [!NOTE] > > The SDKs include companion packages for theming (`@flowx/core-theme`, plus `@flowx/angular-theme`, `@flowx/react-theme`, or `@flowx/react-native-theme`) and UI components (`@flowx/angular-ui-toolkit`, `@flowx/react-ui-toolkit`, or `@flowx/react-native-ui-toolkit`). *** ## Service communication The following diagram shows the typical request flow through the platform: ```mermaid theme={"dark"} 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 Because these steps run asynchronously, long-running processes don't block the user: the UI stays responsive while external systems process requests in the background. *** ## 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 and distributed locks * **Apache Kafka**: event streaming backbone for most 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 (embedded) All services are containerized and designed for Kubernetes deployment. Stateless components support horizontal scaling, and Kafka provides resilient message handling across scaled instances. > [card] [Data architecture](https://docs.flowx.ai/6.x/docs/platform-overview/data-architecture.md) > > Database-to-service mapping and storage details > [card] [Third-party components](https://docs.flowx.ai/6.x/docs/platform-deep-dive/third-party-components.md) > > Supported versions and compatibility matrix *** ## Quick demo