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

# Migrating from 5.1 LTS

> Plan and execute a direct upgrade from FlowX.AI 5.1.x LTS to 5.9.x LTS.

This guide consolidates every breaking change, new service, and required configuration accumulated since the 5.1.x LTS line into the single supported self-hosted upgrade path: **5.1.x → 5.9.x LTS**.

<Info>
  **5.9.0 is the first release in the 5.9.x LTS family** (target 2026-06-02). Monthly LTS patches follow from July 2026. Direct upgrade from 5.1.x LTS to 5.9.0 is the supported self-hosted path.
</Info>

## What changes at a glance

<Frame>
  ![FlowX.AI 5.1.x LTS → 5.9.0 LTS architecture delta](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.9/flowx-5.1-to-5.9-delta.svg)
</Frame>

The diagram above summarizes the upgrade scope: four new backend microservices, an AI Platform reorganization (deprecated services dropped, new services added, the lineup consolidated to 10), a new React Native client SDK, and a new client-provisioned vector database (Qdrant). The sections below cover each area in detail.

### New services since 5.1.x LTS

5.9.0 introduces 13 microservices that did not exist in 5.1.x.

**Backend microservices (4):**

* `email-gateway`. Outbound email delivery
* `organization-manager`. Organization, workspace, and LLM configuration (absorbs the deprecated `ai-platform-models` service)
* `webhook-gateway`. Inbound webhook intake
* `license`. License verification

**AI Platform services (4):**

* `ai-platform-ai-assistant`. Replaces the 5.1.x `ai-assistant` service
* `embedder`. Embedding generation
* `knowledgebase-rag`. Retrieval-augmented generation backend
* `knowledgebase-indexer-v2`. Knowledge base indexing pipeline

**Standalone AI services (5)**. Separate repositories under `flowx-ai/`, installed independently from the AI Platform umbrella chart:

* `doc-parser`
* `doc-converter`
* `web-crawler`
* `data-privacy` (PII Guard)
* `modpod`

**Deprecated in 5.9.0 (9 AI Platform services):** `ai-assistant`, `ai-platform-connected-graph`, `ai-platform-knowledge-graph`, `ai-platform-agents`, `ai-platform-conversations`, `ai-platform-tenants`, `ai-platform-binaries`, `mcp`, `ai-platform-models`. Plan their removal from your deployment manifests during the upgrade.

### Supported upgrade paths

| Source version               | Path                | Notes                                                                                         |
| ---------------------------- | ------------------- | --------------------------------------------------------------------------------------------- |
| **5.1.x LTS**                | Supported           | Direct upgrade from 5.1.x to 5.9.x is supported. The sections below cover the full migration. |
| Any other self-hosted source | FlowX-assisted only | Custom migration plan required. Contact your FlowX representative.                            |

***

## How this guide is organized

Each section below is a self-contained topic. Read them in the order shown for a first-time upgrade; experienced operators can jump directly to the topics that affect them.

<CardGroup cols={2}>
  <Card title="Prerequisites & upgrade path" icon="list-check" href="./prerequisites">
    Audience, supported source versions, inventory you should gather before starting, and what FlowX assists with.
  </Card>

  <Card title="Authentication & IAM migration" icon="shield-keyhole" href="./authentication-iam">
    Keycloak two-realm architecture, service-account client renames, opaque-token removal, SMTP configuration. The largest single break.
  </Card>

  <Card title="Runtime authorization migration" icon="users-gear" href="./runtime-authorization">
    Org-level roles become project-version-scoped. End-user groups move from Keycloak into FlowX. Per-environment sharing.
  </Card>

  <Card title="Organization & deployment configuration" icon="building-shield" href="./organization-deployment">
    Single-org default mode, the `ORGANIZATION_ID` Liquibase parameter on 5 services, the new `license` microservice, and the env-info deprecation.
  </Card>

  <Card title="Kafka migration" icon="message" href="./kafka">
    Mandatory `Fx-Organization-Id` header for every custom producer, new Kafka topics that did not exist in 5.1.x, and one topic-ownership move.
  </Card>

  <Card title="Ingress routing and CORS" icon="network-wired" href="./ingress-routing">
    NGINX ingress controller deprecation, CORS handling moves to the `APPLICATION_CORS_ALLOW_ORIGIN` environment variable, and the optional Gateway API HTTPRoute path.
  </Card>

  <Card title="API & integration breaking changes" icon="code" href="./api-breaking-changes">
    Endpoint rename (`get-input-json` → `get-start-metadata`), `PATCH /api/platform/environment` removed, `Fx-Organization-Id` header mandatory, and opaque-token removal.
  </Card>

  <Card title="Engine partitioning configuration" icon="table-cells" href="./engine-partitioning">
    The partitioning config consolidated under `flowx.data.partitioning.archiving`; the standalone `SCHEDULER_DATA_PARTITIONING_*` variables are gone and the archiving scheduler now defaults to off.
  </Card>
</CardGroup>

### Renderer SDK migration

<CardGroup cols={2}>
  <Card title="Android SDK" icon="android" href="./android">
    Migrate the Android renderer from 5.1.x (9.0.x) to 5.9.x (10.x).
  </Card>

  <Card title="iOS SDK" icon="apple" href="./ios">
    Migrate the iOS renderer from 5.1.x to 5.9.x.
  </Card>

  <Card title="React SDK" icon="react" href="./react">
    Migrate the React renderer from 5.1.x to 5.9.x (includes React 19 upgrade).
  </Card>

  <Card title="Angular SDK" icon="angular" href="./angular">
    Migrate the Angular renderer from 5.1.x to 5.9.x.
  </Card>
</CardGroup>

***

## What this guide assumes

* You are upgrading a **self-hosted 5.1.x LTS deployment**.
* You have agreed the upgrade plan with FlowX in advance. Some 5.1.x deployments may need a custom migration path that this guide does not cover; your FlowX representative will confirm the path before you start.
* You have engaged FlowX for the **Liquibase migration of inactive/archived process instances**. Active instances are migrated automatically; inactive ones require FlowX assistance.

If any of these are not true, contact your FlowX representative before starting. Your path may differ from the one described here.