WSO2 Integration Control Plane

Monitor, troubleshoot, and control integration deployments with a modern GraphQL API and real-time observability.

Architecture

The Integration Control Plane consists of:

• Backend (ICP Server): Ballerina-based GraphQL API service with authentication, runtime management, and observability
• Frontend: Modern React + TypeScript application with Vite and Oxygen UI components
• Database Support: MySQL, PostgreSQL, Microsoft SQL Server, or H2 (in-memory)

Quick Start

Prerequisites

• Java 17+ (for Gradle)
• Ballerina (latest stable version)
• Node.js 20+ and pnpm 10+
• Docker & Docker Compose (recommended for local development)

Running with Docker Compose

The easiest way to get started is using Docker Compose, which sets up the complete stack:

# With MySQL database
docker-compose -f icp_server/docker-compose.mysql.yml up --build

# With PostgreSQL database
docker-compose -f icp_server/docker-compose.postgresql.yml up --build

# With MSSQL database
docker-compose -f icp_server/docker-compose.mssql.yml up --build

The services will be available at:

• Frontend: http://localhost:5173
• GraphQL API: https://localhost:9446/graphql
• Authentication API: https://localhost:9446/auth
• Observability API: https://localhost:9446/icp/observability

Default credentials: admin / admin

Building from Source

Complete Build

Build the entire project using Gradle:

./gradlew build

Or use the build script:

./build.sh

The distribution package will be created as:

build/distribution/wso2-integration-control-plane-<version>.zip

Running the Distribution

After building, extract and run the packaged distribution:

# Extract the distribution
unzip build/distribution/wso2-integration-control-plane-<version>.zip -d build/distribution

# Navigate to the bin directory
cd build/distribution/wso2-integration-control-plane-<version>/bin

# Start the server
./icp.sh    # Linux/macOS
icp.bat    # Windows

Development Setup

Backend Development

Navigate to the backend directory:

cd icp_server

Using Docker Compose (Recommended)

# Start with local configuration (H2 database)
docker-compose -f docker-compose.local.yml up --build

# Start with MySQL
docker-compose -f docker-compose.mysql.yml up --build

# Start with observability stack (Prometheus, Grafana)
docker-compose -f docker-compose.observability.yml up --build

Running Locally with Ballerina

1. Configure the database in icp_server/Config.toml
2. Run the service:

bal run

The server will start on port 9446

Frontend Development

Navigate to the frontend directory:

cd frontend

Install Dependencies

pnpm install

Configure Backend URLs

Edit frontend/public/config.json:

{
  "VITE_GRAPHQL_URL": "https://localhost:9446/graphql",
  "VITE_AUTH_BASE_URL": "https://localhost:9446/auth",
  "VITE_OBSERVABILITY_URL": "https://localhost:9446/icp/observability"
}

Start Development Server

pnpm dev

The frontend will be available at http://localhost:5173

Build for Production

pnpm build

The production build will be in frontend/dist/

Database Configuration

The ICP Server supports multiple database backends:

MySQL

# icp_server/Config.toml
[icp_server.storage]
dbType = "mysql"
host = "localhost"
port = 3306
name = "icp_db"
username = "root"
password = "root"

PostgreSQL

[icp_server.storage]
dbType = "postgresql"
host = "localhost"
port = 5432
name = "icp_db"
username = "postgres"
password = "postgres"

Microsoft SQL Server

[icp_server.storage]
dbType = "mssql"
host = "localhost"
port = 1433
name = "icp_db"
username = "SA"
password = "YourStrong@Passw0rd"

H2 (In-Memory)

[icp_server.storage]
dbType = "h2"

Testing

Backend Tests

# Self-contained: seeds H2 test databases, then runs `bal test` with coverage
./gradlew testICP

Frontend Tests

cd frontend
pnpm test

Authentication

The ICP supports multiple authentication methods:

• Default User Backend: Built-in user management with JWT tokens
• Custom Auth Backend: Integration with external OAuth2/OIDC providers
• LDAP: Enterprise directory integration

See icp_server/custom_auth/AUTH_BACKEND_IMPLEMENTATION.md for details.

Observability

The ICP Server integrates with:

• OpenSearch: For log aggregation and search
• Prometheus: For metrics collection
• Grafana: For visualization

Start the observability stack:

cd icp_server
docker-compose -f docker-compose.observability.yml up

Documentation

• Backend Documentation
• Frontend Documentation
• Runtime Configuration
• RBAC v2 Implementation
• Kubernetes Deployment

Project Structure

integration-control-plane/
├── icp_server/              # Ballerina backend service
│   ├── modules/             # Ballerina modules (auth, storage, observability)
│   ├── tests/               # Backend tests
│   ├── database/            # Database schemas and migrations
│   └── docker-compose.*.yml # Docker Compose configurations
├── frontend/                # React TypeScript frontend
│   ├── src/                 # Source code
│   ├── public/              # Static assets and runtime config
│   └── dist/                # Production build output
├── distribution/            # Distribution scripts
├── kubernetes/              # Kubernetes deployment manifests
└── build.gradle             # Gradle build configuration

License

This project is licensed under the Apache License 2.0. See the LICENSE file for details.

Support

• Issue Tracker
• WSO2 Support