FlowX.AI is built on a modern microservices architecture, allowing for scalable, resilient, and flexible deployments. Each microservice operates independently while collaborating with others to provide a complete enterprise solution.

Deployment strategy

Deploying FlowX.AI microservices involves breaking down the application into modular components that can be independently deployed, scaled, and maintained. All microservices are delivered as Docker containers, making them suitable for deployment on any container orchestration platform, such as Kubernetes or Docker Swarm.

Deployment prerequisites

Before beginning the deployment process, ensure you have:

  • A Kubernetes cluster or Docker environment
  • Access to a container registry
  • Persistent storage for databases
  • Network policies configured for inter-service communication
  • Resource quotas and limits defined for each environment

Following the correct installation sequence is crucial for a successful deployment. This ordered approach prevents dependency issues and ensures each service has the required dependencies available when it initializes.

1

Infrastructure Components

First, deploy the foundational infrastructure:

  • Databases: PostgreSQL/Oracle for relational data, MongoDB for document storage
  • Message Broker: Kafka and ZooKeeper
  • Caching: Redis
  • Identity Management: Keycloak or other OAuth2 provider
2

Core Components

Next, deploy these core services in order:

  1. Advancing Controller: Manages process advancement and orchestration
  2. Process Engine: Handles business process execution and state management
3

Backend Services

Once the core components are operational, deploy these services (can be deployed in parallel):

  • Admin Service: Platform administration and configuration management
  • Audit Core: Compliance auditing and activity tracking
  • Task Management: Human task assignment and workflow
  • Scheduler Core: Job scheduling and time-based operations
  • Data Search: Indexing and searching capabilities
  • License Core: License management and validation
  • Events Gateway: Event routing and processing
  • Document Plugin: Document generation and management
  • Notification Plugin: Communication and alerts management
  • Any additional plugins or extensions
4

Frontend Components

Finally, deploy the frontend services:

  • Designer: Process design environment for business analysts
  • Web Components: UI components for custom applications
  • Customer-facing UIs and portals

Environment variables reference

Environment variables are the primary configuration mechanism for FlowX.AI microservices. They provide a secure and flexible way to customize service behavior without modifying the container images.

Common environment variables

The following sections detail the most commonly used environment variables across FlowX.AI microservices. For service-specific variables, refer to the dedicated setup guides for each component.

Authorization & access management

Environment VariableDescriptionExample ValueRequired
SECURITY_OAUTH2_BASESERVERURLBase URL of the OAuth2/OIDC serverhttps://keycloak.example.com/authYes
SECURITY_OAUTH2_CLIENTCLIENTIDOAuth2 client ID for the serviceflowx-admin-serviceYes
SECURITY_OAUTH2_CLIENTCLIENTSECRETOAuth2 client secretsecretYes
SECURITY_OAUTH2_REALMOAuth2 realm nameflowxYes
SECURITY_OAUTH2_SERVICEACCOUNT_ADMIN_CLIENTIDService account client ID (for inter-service auth)flowx-service-accountNo*
SECURITY_OAUTH2_SERVICEACCOUNT_ADMIN_CLIENTSECRETService account client secretsecretNo*

*Required for some services that need to make authenticated calls to other services

Database configuration

PostgreSQL/Oracle
Environment VariableDescriptionExample ValueRequired
SPRING_DATASOURCE_URLJDBC connection URLjdbc:postgresql://postgres:5432/flowxYes
SPRING_DATASOURCE_USERNAMEDatabase usernameflowx_userYes
SPRING_DATASOURCE_PASSWORDDatabase passwordsecurePassword123Yes
SPRING_DATASOURCE_DRIVERCLASSNAMEJDBC driver class (Oracle only)oracle.jdbc.OracleDriverYes*
SPRING_JPA_PROPERTIES_HIBERNATE_DEFAULTSCHEMADefault schema (Oracle only)FLOWXYes*

*Required only for Oracle databases

MongoDB
Environment VariableDescriptionExample ValueRequired
SPRING_DATA_MONGODB_URIMongoDB connection URImongodb://mongo1,mongo2,mongo3:27017/flowx?replicaSet=rs0Yes
DB_USERNAMEMongoDB username for services that need itflowx_mongo_userYes
DB_PASSWORDMongoDB passwordmongoSecurePass456Yes
SPRING_DATA_MONGODB_RUNTIME_ENABLEDEnable runtime MongoDB connectiontrueNo
SPRING_DATA_MONGODB_RUNTIME_URIURI for runtime MongoDB connectionmongodb://${DB_USERNAME}:${DB_PASSWORD}@mongodb-runtime:27017/app-runtimeNo*

*Required if runtime MongoDB connection is enabled

Kafka Configuration

Environment VariableDescriptionExample ValueRequired
SPRING_KAFKA_BOOTSTRAPSERVERSComma-separated list of Kafka brokerskafka-0:9092,kafka-1:9092,kafka-2:9092Yes
SPRING_KAFKA_SECURITY_PROTOCOLSecurity protocol for Kafka communicationSASL_PLAINTEXTNo
SPRING_KAFKA_CONSUMER_GROUPIDConsumer group IDflowx-process-engine-groupYes
KAFKA_CONSUMER_THREADSNumber of Kafka consumer threads5No
KAFKA_AUTHEXCEPTIONRETRYINTERVALRetry interval for auth exceptions (seconds)10No
KAFKA_MESSAGE_MAX_BYTESMaximum Kafka message size (bytes)52428800 (50MB)No

Topic Naming Configuration

For services that communicate via Kafka, the topic naming follows a convention:

Environment VariableDescriptionExample ValueRequired
KAFKA_TOPIC_NAMING_SEPARATORPrimary topic name separator.No
KAFKA_TOPIC_NAMING_SEPARATOR2Secondary topic name separator-No
KAFKA_TOPIC_NAMING_PACKAGEPackage prefix for topicsai.flowx.No
KAFKA_TOPIC_NAMING_ENVIRONMENTEnvironment segmentdev.No
KAFKA_TOPIC_NAMING_VERSIONVersion suffix.v1No

The engine and other services listen for messages on topics with specific naming patterns. Ensure you use correct topic names to maintain proper inter-service communication.

Redis configuration

Environment VariableDescriptionExample ValueRequired
SPRING_REDIS_HOSTRedis server hostnameredis-masterYes
SPRING_REDIS_PORTRedis server port6379Yes
SPRING_REDIS_PASSWORDRedis passwordredisPassword789Yes
REDIS_TTLCache TTL in milliseconds5000000No

Logging configuration

Environment VariableDescriptionExample ValueRequired
LOGGING_LEVEL_ROOTRoot logging levelINFONo
LOGGING_LEVEL_APPApplication-specific logging levelDEBUGNo
LOGGING_LEVEL_MONGO_DRIVERMongoDB driver logging levelWARNNo
LOGGING_LEVEL_KAFKAKafka client logging levelWARNNo
LOGGING_LEVEL_REDISRedis client logging levelOFFNo

Deployment best practices

High availability considerations

For production environments, configure these high availability features:

  • Database Clustering: Implement PostgreSQL/Oracle with replication
  • MongoDB Replica Sets: Deploy MongoDB as a replica set with at least 3 nodes
  • Kafka Clustering: Use at least 3 Kafka brokers with replication factor ≥ 3
  • Redis Sentinel/Cluster: Configure Redis for high availability
  • Service Replicas: Run multiple instances of each microservice
  • Load Balancing: Implement proper load balancing for service instances
  • Affinity/Anti-Affinity Rules: Distribute service instances across nodes

Security recommendations

Secure your FLOWX.AI deployment with these measures:

  1. Network Segmentation: Isolate microservices using network policies
  2. Secret Management: Use Kubernetes Secrets or a vault solution
  3. TLS Everywhere: Enable TLS for all service-to-service communication
  4. OAuth2 Scopes: Configure fine-grained OAuth2 scopes for services
  5. Resource Isolation: Use namespaces and pod security policies
  6. Regular Updates: Keep all components updated with security patches
  7. Audit Logging: Enable comprehensive audit logging via the Audit Core service

Troubleshooting

Common issues and solutions

IssuePossible causeSolution
Service fails to startMissing environment variablesCheck logs for “Configuration property not found” errors
Database connection errorsIncorrect credentials or URLVerify database connection parameters
Services can’t communicateKafka misconfigurationEnsure topic names match between producer and consumer services
Authentication failuresOAuth2 configuration issuesVerify client IDs, secrets, and server URLs
Performance degradationInsufficient resourcesMonitor CPU/memory usage and scale resources appropriately
Data inconsistencyRedis cache not synchronizedCheck Redis connection and consider cache invalidation

Diagnostic procedures

When troubleshooting FlowX.AI microservices:

  1. Check Service Logs: Examine logs for error messages
  2. Verify Configurations: Ensure all required environment variables are set correctly
  3. Test Connectivity: Verify network connectivity between services
  4. Monitor Resources: Check CPU, memory, and disk usage
  5. Inspect Kafka Topics: Use Kafka tools to inspect message flow
  6. Review Database State: Examine database for data integrity issues
  7. Check OAuth2 Tokens: Verify token validity and permissions

Service-specific documentation

For detailed configuration of individual services, refer to: