# rcelha/rio-rs architecture

> Architecture diagram of the GitHub repository rcelha/rio-rs, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-08). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/rcelha/rio-rs
- Repository: https://github.com/rcelha/rio-rs

## Overview

##### Main Components
- Registry – The component responsible for registering different ServiceObjects and their associated messages. It is central to routing incoming requests to the correct service.
- Cluster Membership Provider – This is part of the distributed aspect and is implemented using different storage backends (e.g., SQLite, Redis, PostgreSQL). It enables nodes to discover one another and maintain cluster membership.
- Object Placement Provider – This subsystem manages the mapping of service objects to specific servers or nodes. It too can utilize SQL storage or similar backends.
- Client – A client component (illustrated by the ClientBuilder and message sending examples) is used to interact with the Server, send messages, and handle responses.
- Message Handling/Service Objects – These represent the “actors” or components (often built with macros supported by the project such as those in rio-macros) that encapsulate the service logic.
- Additional Building Blocks – The project also includes examples (like black-jack, metric-aggregator, ping-pong, custom-storage, presence) demonstrating how to use the framework. They show client/server interactions, service invocation, and varied use-cases (e.g., pub/sub and async tasks).

- From the Server, illustrate how the incoming request is passed to the Registry, which then dispatches it to the corresponding ServiceObject (or handler) based on type.
- That ServiceObjects might interact with underlying storage or databases via the Cluster Membership Provider and Object Placement Provider.

##### Architectural Patterns and Design Principles
- Distributed Messaging/Message-Passing – Emphasize the decoupled communication mechanism between Clients and ServiceObjects.
- Modular Design – Capture how different layers (Registry, messaging / service handling, cluster management, and storage backends) separate concerns within the framework.
- Extensibility – Note the use of macros (in rio-macros) for generating boilerplate and enforcing type-safe message and service definitions.

##### Relevant Technologies and Frameworks
- Rust (the language used, with its async ecosystem, primarily Tokio for asynchronous runtime).
- SQL-based storage (SQLite is explicitly showcased, with comments hinting at MySQL/PostgreSQL alternatives).
- Redis for in-memory state and cluster management.
- GitHub Actions (CI configurations from .github/workflows) indicate testing and continuous integration practices.

##### Additional Details
- Point out that the macros directory (rio-macros) is an important helper tool that simplifies the creation and routing of messages and service objects. You might position this as a “helper module” that underpins the ServiceObjects.

Happy diagramming!

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Layer
    subgraph "Client Layer"
        client("Client"):::client
    end

    %% Core Framework
    subgraph "Core Framework"
        server("Server"):::server
        registry("Registry"):::registry
        serviceObjects("Service Objects"):::service
        server -->|"dispatch"| registry
        registry -->|"routeMessage"| serviceObjects
        serviceObjects -->|"processMessage"| server
    end

    %% Providers Layer
    subgraph "Providers"
        cluster("Cluster Membership Provider"):::provider
        objectPlacement("Object Placement Provider"):::provider
        server -->|"clusterUpdate"| cluster
        server -->|"placementUpdate"| objectPlacement
        cluster -->|"membershipStatus"| server
        objectPlacement -->|"placementStatus"| server
    end

    %% Helpers Layer
    subgraph "Helpers"
        macros("Macros Helper Module"):::macro
        macros -->|"assist"| serviceObjects
    end

    %% Examples Layer
    subgraph "Examples"
        examples("Example Services"):::example
        examples -->|"demoClient"| client
    end

    %% Message flow between Client and Core Framework
    client -->|"sendMessage"| server
    server -->|"returnResponse"| client

    %% Styles
    classDef server fill:#ffcccc,stroke:#cc0000,stroke-width:2px;
    classDef client fill:#ccffcc,stroke:#009900,stroke-width:2px;
    classDef registry fill:#cce5ff,stroke:#003366,stroke-width:2px;
    classDef provider fill:#ffffcc,stroke:#999900,stroke-width:2px;
    classDef service fill:#ffe6cc,stroke:#cc6600,stroke-width:2px;
    classDef macro fill:#e6ccff,stroke:#6600cc,stroke-width:2px;
    classDef example fill:#ffd9b3,stroke:#ff6600,stroke-width:2px;

    %% Click Events
    click server "https://github.com/rcelha/rio-rs/blob/main/rio-rs/src/server.rs"
    click registry "https://github.com/rcelha/rio-rs/tree/main/rio-rs/src/registry"
    click cluster "https://github.com/rcelha/rio-rs/tree/main/rio-rs/src/cluster"
    click objectPlacement "https://github.com/rcelha/rio-rs/tree/main/rio-rs/src/object_placement"
    click client "https://github.com/rcelha/rio-rs/tree/main/rio-rs/src/client"
    click serviceObjects "https://github.com/rcelha/rio-rs/blob/main/rio-rs/src/service_object.rs"
    click macros "https://github.com/rcelha/rio-rs/tree/main/rio-macros"
    click examples "https://github.com/rcelha/rio-rs/tree/main/examples"
```
