# Circles Project

Welcome to the `circles` project, a full-stack system featuring a WebSocket server, a cross-platform client, and a launcher to manage multiple instances. This project is designed for executing Rhai scripts in isolated environments, with an optional layer of `secp256k1` cryptographic authentication.

## Overview

The `circles` project provides two core library crates and a utility application:

- **`server_ws`**: The core WebSocket server library, built with `Actix`. It handles client connections, processes JSON-RPC messages, and executes Rhai scripts.
- **`client_ws`**: The core cross-platform WebSocket client library, compatible with both native Rust and WebAssembly (WASM) environments.
- **`launcher`**: A convenient command-line utility that uses the `server_ws` library to read a `circles.json` configuration file and spawn multiple, isolated "Circle" instances.
- **`openrpc.json`**: An OpenRPC specification that formally defines the JSON-RPC 2.0 API used for client-server communication.

## Architecture

The system is designed around a client-server model, with `client_ws` and `server_ws` as the core components. The `launcher` is provided as a utility for orchestrating multiple server instances, each configured as an isolated "Circle" environment.

Clients connect to a `server_ws` instance via WebSocket and interact with it using the JSON-RPC protocol. The server can be configured to require authentication, in which case the client must complete a signature-based challenge-response flow over the WebSocket connection before it can execute protected methods like `play`.

For a more detailed explanation of the system's design, please see the [ARCHITECTURE.md](ARCHITECTURE.md) file.

## Getting Started

To run the system, you will need to use the `launcher`.

1.  **Configure Your Circles**: Create a `circles.json` file at the root of the project to define the instances you want to run. Each object in the top-level array defines a "Circle" with a unique `id`, `port`, and associated database and script paths.

    ```json
    [
      {
        "id": "circle-1",
        "port": 9001,
        "db_path": "/tmp/circle-1.db",
        "rhai_path": "/path/to/your/scripts"
      }
    ]
    ```

2.  **Run the Launcher**:
    ```bash
    cargo run --package launcher
    ```

The launcher will start a WebSocket server for each configured circle on its specified port.

## API

The client-server communication is handled via JSON-RPC 2.0 over WebSocket. The available methods are:

- `play`: Executes a Rhai script.
- `authenticate`: Authenticates the client.

For a complete definition of the API, including request parameters and response objects, please refer to the [openrpc.json](openrpc.json) file.

## Crates

- **[server_ws](server_ws/README.md)**: Detailed documentation for the server library.
- **[client_ws](client_ws/README.md)**: Detailed documentation for the client library.
- **[launcher](launcher/README.md)**: Detailed documentation for the launcher utility.
- **[app](src/app/README.md)**: A Yew frontend application that uses the `client_ws` to interact with the `server_ws`.

## Running the App

To run the `circles-app`, you'll need to have `trunk` installed. If you don't have it, you can install it with:

```bash
cargo install trunk wasm-bindgen-cli
```

Once `trunk` is installed, you can serve the app with:

```bash
cd src/app && trunk serve
```