FlowX.AI architecture: services, layers, and data flow

​

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.

---

​

Architecture overview

The architecture diagram shows the main 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).

---

​

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.

---

​

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: 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, and SSE connections, all routed through the API Gateway.

---

​

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, advancing), MongoDB (app-runtime read), Redis (cache), Elasticsearch (indexing)

​

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)

​

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

​

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)

---

​

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)

​

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)

​

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)

​

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)

​

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)

---

​

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)

​

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)

​

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 and SpiceDB work together to enforce tenant boundaries while allowing users to belong to multiple workspaces.

​

Identity providers

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

---

​

Plugins

Plugins are modular extensions that add domain-specific capabilities to the core platform.

​

Document Plugin

The Document Plugin 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 (qdevlocal-preview-paperflow prefix, temp-bucket)

​

Notification Plugin

The Notification Plugin 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 Plugin

The Task Management Plugin 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)

​

OCR Plugin

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

---

​

Supporting services

Supporting services provide cross-cutting capabilities such as auditing.

​

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)

---

​

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

The AI Platform comprises 14 specialized services handling agent orchestration, conversation management, knowledge graphs, model routing, and config-time assistance (AI Developer, AI Analyst, AI Designer).

---

​

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.

---

​

Service communication

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

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
• Dgraph: graph database for AI Platform agent state and knowledge graphs (embedded)

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

---

​

Quick demo

---

​

Related resources