Architecture

Architecture

Ripple sits between Firebolt apps and platform providers, translating API calls and enforcing capabilities and grants. It serves as a middleware layer that manages communication, security, and functionality routing between applications and various backend services.

High-Level Architecture

System Overview

Key Components:

• Gateway Layer:

  • Gateway Server: Manages WebSocket connections and JSON-RPC communication
  • Configuration Manager: Manages system configuration and manifests
  • App Management:
    • AppSessionManager: Handles app session state and management
    • AppLifecycleManager: Controls application lifecycle states
    • AppEvents: Manages application event handling and distribution

• Request Processing:

  • RpcRouter: Routes and validates JSON-RPC requests
  • OpenRPCValidator: Validates requests against OpenRPC specifications
  • RuleEngine: Processes and applies routing and transformation rules
  • Security:
    • Permission Authorization: Manages API access permissions
    • UserGrants: Handles user-specific permissions and grants

• Endpoint Routing:

  • Endpoint Broker: Central routing component for all protocol-specific communication
  • Protocol Brokers:
    • Thunder Broker: Handles Thunder protocol communication
    • Service Broker: WebSocket based broker for operator services (BYOS)
    • WebSocket Broker: Manages WebSocket connections
    • HTTP Broker: Handles HTTP/REST communication

• Service Management:

  • Service Controller: Orchestrates service management and communication, interacts directly with Gateway Server
  • Service Registry: Maintains catalog of available services and their capabilities

• Backend Services:

  • Thunder Services: Native device services via Thunder protocol
  • WebSocket Services: Real-time communication services
  • HTTP Services: RESTful services
  • Operator Service: BYOS (Bring Your Own Service) implementation from operators, accessed via Service Broker

Boot Process

1. Initialization: Gateway Main starts and loads configuration
2. Service Loading: Core services are initialized
3. Extension Loading: Device and operator extensions are loaded
4. Manifest Processing: Configuration manifests are parsed and applied
5. Broker Initialization: Communication brokers are established
6. Gateway Server Start: WebSocket server begins accepting connections

Firebolt Gateway WebSocket Server

• Manages WebSocket connections from Firebolt applications
• Handles connection lifecycle (connect, authenticate, disconnect)
• Maintains session state for each connected application
• Processes incoming JSON-RPC requests
• Routes responses and events back to applications

Connection Management

• Application Connections:
  • Authentication and authorization
  • Session tracking
  • Connection pooling
  • Event subscription management
• Service Connections:
  • Connection establishment with backends
  • Connection health monitoring
  • Automatic reconnection

Function Routing

1. Request arrives at Gateway
2. Request is validated and authenticated
3. Function name is matched against routing rules
4. Request is forwarded to appropriate handler
5. Handler processes request through relevant broker
6. Response is transformed and returned

Broker Architecture and Request Routing

Ripple uses a sophisticated broker system to route requests from Firebolt applications to appropriate backend providers based on configured rules.

graph LR
    A1[Firebolt App 1]
    A2[Firebolt App 2]
    G[Ripple Gateway]
    B1[Thunder]
    B2[WebSocket]
    B3[HTTP]
    P1[Thunder Plugins]
    P2[Internal WS Services]
    P3[Backend HTTP APIs]
    
    subgraph Apps
        A1
        A2
    end
    
    subgraph Brokers
        B1
        B2
        B3
    end
    
    subgraph Providers
        P1
        P2
        P3
    end
    
    A1-->|JSON-RPC/WS|G
    A2-->|JSON-RPC/WS|G
    G---B1
    G---B2
    G---B3
    B1---P1
    B2---P2
    B3---P3

Loading

Broker Types

1. Thunder Broker:

   • Manages WebSocket connections to Thunder plugins
   • Handles request/response cycles
   • Manages event subscriptions
   • Provides connection pooling

2. WebSocket Broker:

   • Handles persistent WebSocket connections
   • Manages real-time event streaming
   • Provides bi-directional communication

3. HTTP Broker:

   • Manages REST API communications
   • Handles request/response transformations
   • Supports various authentication methods

Request Flow

1. Firebolt app sends request to Gateway
2. Gateway matches request against rules
3. Request is routed to appropriate broker
4. Broker transforms request if needed
5. Request is sent to provider
6. Response is transformed and returned

Rule-Based Routing

• Rules defined in configuration files
• Method patterns determine routing
• Support for request/response transformations
• Event subscription management
• Error handling and fallbacks

Runtime Components

• Gateway Main:

  • Core process that starts services
  • Loads and manages extensions
  • Coordinates system components

• Extensions:

  • Implement device/operator logic through contracts
  • Provide modular functionality
  • Enable platform customization
  • Note: Extensions will be deprecated in future versions and replaced with Extension as Service.

• IEC (Inter-Extension Communication):

  • Enables typed requests/events between extensions
  • Manages extension dependencies
  • Coordinates extension interactions
  • Note: IEC will be deprecated in future versions and replaced with Service Messages.

• Manifests:

  • Define bootstrap configurations
  • Specify device capabilities
  • List available applications
  • Configure extension parameters

Service Architecture

Service Controller

• Manages service lifecycle
• Handles service registration/deregistration
• Monitors service health
• Manages service configuration
• Coordinates service updates

Service Registry

• Maintains catalog of available services
• Tracks service endpoints and capabilities
• Manages service dependencies
• Provides service discovery
• Updates service status

Service API Routing

• Routes requests to appropriate services
• Handles service versioning
• Manages API transformations
• Implements fallback logic
• Provides error handling

Service Interaction

Service Extensibility

Ripple supports dynamic service integration through its BYOS (Bring Your Own Service) architecture, allowing operators to extend the platform with their own services and functionality. This enables custom implementations while maintaining standardization and security.

Learn more about BYOS : Bring Your Own Service

See also: Manifests, Brokers and Rules System.