circles/research/launcher/ARCHITECTURE.md

launcher Architecture

This document provides a detailed look into the internal architecture of the launcher utility, explaining how it orchestrates the creation and management of multiple Circle instances.

1. Core Design

The launcher is a tokio-based asynchronous application. Its primary responsibility is to parse a configuration file and then spawn and manage the lifecycle of two key components for each configured Circle:

1. A server instance: A WebSocket server running in its own tokio task.
2. A Rhai worker: A script execution engine running in a separate tokio task.

The launcher maintains a central registry of all running circles, allowing it to monitor their status and coordinate a graceful shutdown.

2. Startup and Initialization Sequence

The main function in launcher/src/main.rs executes the following sequence:

1. Parse Command-Line Arguments: It checks for verbosity flags (-v, -vv, -vvv) and a debug flag (-d) to configure the logging level.
2. Load Configuration: It reads and deserializes the circles.json file into a Vec<CircleConfig>.
3. Iterate and Spawn: For each CircleConfig in the vector, it performs the following steps: a. Database Setup: It creates a dedicated database directory for the Circle at ~/.hero/circles/{id}/. b. Rhai Engine Initialization: It creates an instance of the Rhai engine and, if a script_path is provided, executes the initial script. c. Worker Spawning: It calls worker_lib::spawn_rhai_worker, which starts the Rhai worker in a new tokio task. It provides the worker with a shutdown channel receiver. d. Server Spawning: It calls circle_ws_lib::spawn_circle_ws_server, which starts the Actix WebSocket server in another tokio task. It provides the server with a channel to send back its ServerHandle.
4. Store Handles: It stores all the necessary handles for each running circle—including the worker's shutdown channel sender and the server's ServerHandle—in a central Vec<RunningCircleInfo>.
5. Display Status: It prints a table to the console with details about each running circle.

3. Graceful Shutdown

The launcher is designed to shut down all its child processes cleanly when it receives a Ctrl+C signal.

sequenceDiagram
    participant User
    participant Launcher as main()
    participant Worker as Rhai Worker Task
    participant Server as WS Server Task

    User->>Launcher: Presses Ctrl+C
    Launcher->>Launcher: Catches signal::ctrl_c()

    loop For Each Running Circle
        Launcher->>Worker: Sends shutdown signal via mpsc::channel
        Launcher->>Server: Calls handle.stop(true)
    end

    Note over Launcher: Waits for all tasks to complete.

    Launcher->>User: Exits cleanly

This process ensures that both the WebSocket servers and the Rhai workers have a chance to terminate properly, preventing orphaned processes and potential data corruption.