⚡ OpenBalancer & INCONTROL PLUS Ecosystem

🇧🇬 Българска версия (Bulgarian Version) | 🇬🇧 English Version

OpenBalancer is a modern, high-performance, asynchronous load balancer, reverse proxy, and open-source infrastructure suite engineered by INCONTROL PLUS ЕООД. Built for AI inference clusters, high-throughput microservices, and mission-critical API routing.

🏗️ Repository Architecture

openbalancer/
├── README.md                                # Root Documentation (English)
├── README.bg.md                             # Root Documentation (Bulgarian)
├── LICENSE                                  # MIT Open Source License
├── core/                                    # OpenBalancer Core Engine & Testing
│   ├── openbalancer.py                      # Asynchronous Python Load Balancer & Proxy
│   ├── config.json                          # Sample Node & Strategy Configuration
│   ├── Dockerfile                           # Production Alpine Docker Image
│   ├── docker-compose.yml                   # Cluster Sandbox with Upstream Mocks
│   ├── test_balancer.py                     # Automated Verification Test Suite
│   ├── awesome-selfhosted-pr.md             # Awesome-Selfhosted PR Submission
│   └── README.md                            # Engine-specific Documentation
├── website/                                 # Official Website (Cloudflare Pages)
│   ├── index.html                           # Landing Page with Interactive Traffic Simulator
│   ├── css/style.css                        # Modern Vanilla CSS Theme & Animations
│   ├── js/main.js                           # Real-time Balancer Visualizer Logic
│   ├── terms.html                           # Terms of Service
│   ├── privacy.html                         # GDPR-Compliant Privacy Policy
│   ├── refunds.html                         # SLA Credit & Refund Policy
│   ├── contact.html                         # Impressum & Corporate Verification
│   └── _headers                             # Security Headers (CSP, HSTS, X-Frame)
├── compliance/                              # Legal Framework & Commercial Contracts
│   ├── Brand_Isolation_Legal_Matrix.md      # 3-Tier Corporate & Anti-Fronting Hierarchy
│   ├── B2B_Master_Services_Agreement_Template.md # Enterprise B2B Contract Template
│   ├── B2B_Statement_Of_Work_SLA_Template.md     # 99.9% Uptime SLA Specification
│   ├── Stripe_Onboarding_Step_by_Step_Guide.md  # Stripe KYB & Approval Guide
│   └── FinansProtect_B2B_Billing_Workflow.md    # Third-party Client Invoicing Flow
├── cloudflare/                              # Zero-Cost Edge Hosting & DNS
│   └── Cloudflare_Pages_and_DNS_Deployment_Guide.md # CI/CD & Custom Domain Setup
└── social/                                  # Brand Visibility & Digital Footprint
    ├── LinkedIn_Company_Page_Copy.md        # INCONTROL PLUS Company Profile
    ├── LinkedIn_Product_Page_Copy.md        # OpenBalancer Showcase Profile
    ├── Twitter_Launch_Strategy.md           # Announcement & Feature Threads
    └── Discord_Community_Setup.md           # Developer & Support Server Structure

🌟 Core Engine Features

• ⚡ Non-Blocking Async I/O: Pure Python async proxy with sub-millisecond overhead (p50 < 4.7ms).
• 🧠 AI & LLM Inference Aware: Zero-buffer chunked transfers and SSE (Server-Sent Events) passthrough.
• 🛡️ Active Health Checks & Circuit Breaker: Automated background health monitoring with automatic traffic draining and failover.
• 🎯 Routing Strategies: round_robin, weighted_round_robin, least_connections, least_latency, ip_hash, power_of_two.
• 📊 Dual Observability API:
  • JSON Status Endpoint: /openbalancer/status
  • Prometheus Plaintext Metrics Exporter: /metrics
• 📈 Official Grafana Dashboard: Ready-to-import template in telemetry/grafana-openbalancer-dashboard.json.
• 🐳 Docker & Kubernetes Ready: Ultralight multi-arch container footprint (<45MB).

🚀 Quickstart

0. Install via PyPI (Recommended for CLI & Python API)

pip install openbalancer

# Launch interactive demo sandbox with 3 mock backends:
openbalancer demo

# Or start with custom configuration:
openbalancer start -c config.json

1. Instant Interactive Demo Sandbox (Zero Configuration)

Launch OpenBalancer together with 3 built-in mock upstream backends (ALPHA, BETA, GAMMA) in a single command:

python3 core/openbalancer.py demo
# Or on custom port:
python3 core/openbalancer.py demo -p 8088

Now in another terminal:

# Send load balanced requests across ALPHA, BETA, GAMMA:
curl -s http://localhost:8088/

# Inspect real-time cluster telemetry:
curl -s http://localhost:8088/openbalancer/status | jq .
curl -s http://localhost:8088/metrics

2. Standard Production Mode (Custom Upstream Targets)

# Validate your configuration
python3 core/openbalancer.py validate -c core/config.json

# Start OpenBalancer service
python3 core/openbalancer.py start -c core/config.json

Or 1-line curl installer:

curl -fsSL https://www.openbalancer.com/install.sh | bash

3. Run Turnkey Docker Mesh (OpenBalancer + Prometheus + Grafana)

docker compose -f docker-compose.mesh.yml up -d

4. Run High-Concurrency Benchmark (5,300+ RPS)

python3 benchmark/run_benchmark.py

View full benchmark results: benchmark/BENCHMARK_RESULTS.md.

3. Run Automated Unit & Verification Tests

python3 -m unittest discover -s tests -p "test_*.py" -v
python3 core/test_balancer.py

4. Prometheus & Grafana Monitoring

OpenBalancer exports standard Prometheus metrics on /metrics:

curl http://localhost:8088/metrics
curl http://localhost:8088/openbalancer/status

Import telemetry/grafana-openbalancer-dashboard.json into Grafana for real-time throughput and health telemetry.

📚 Technical Documentation

Explore in-depth documentation in docs/:

• Architecture & Event Loop
• Routing Algorithms
• Configuration Schema
• Telemetry & Prometheus API
• Production Deployment

🏢 Enterprise Support & SLAs

OpenBalancer is maintained and commercially operated by INCONTROL PLUS ЕООД (Sofia, Bulgaria). We offer dedicated enterprise services:

• 99.9% Guaranteed Monthly Uptime SLA
• Sub-15 Minute Incident Response
• Net-14 Corporate Invoicing & Stripe Card Payments
• Custom AI Routing & Load Balancer Module Engineering
• Managed Turnkey Infrastructure Deployments

For inquiries, contact: support@openbalancer.com or visit https://www.openbalancer.com.

📜 License & Compliance

• Software License: Distributed under the MIT License.
• Corporate Operator: INCONTROL PLUS ЕООД, Sofia, Bulgaria (UIC 204882190).
• Compliance: Full GDPR, Stripe KYB, and EU consumer protection alignment.