# jayson-aron/robot-worlds architecture

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

- Interactive diagram: https://gitdiagram.com/jayson-aron/robot-worlds
- Repository: https://github.com/jayson-aron/robot-worlds

## Overview

##### Project type and purpose
- This is a Java-based, Maven multi-module client–server game called “Robot-Worlds.”
- The server hosts an in-memory grid world and listens for TCP connections; the client launches robot instances, sends commands, and renders responses.

##### File structure
- Top-level POM (`pom.xml`) aggregates two modules:
- `server/` – implements the game world, server protocols, command handlers, world state generators, console interface, and an optional GUI renderer (`guiworldstate`).
- `client/` – implements networked clients, robot classes (Recon, Sniper, Assassin, Soldier), session/instance handlers, and client-side protocols.
- `worlds_config` and `client_config` live at the root to configure world parameters (grid size, visibility, respawn times, etc.) and client’s target IP/port.
- A third-party library (`java-turtle-1.0-SNAPSHOT.jar`) under `libs/` provides drawing utilities for rendering the world (used by server’s GUI or client diagnostics).
- Both modules include unit tests for protocols and core logic.

##### README for additional insights
- The server is started by running `server.jar`; it reads `worlds_config`, spins up `SimpleServer`, and accepts console commands (e.g., `dump`, `purge`).
- Clients run `client.jar`, read `client_config`, connect over TCP, and instantiate robot threads to interact with the world using a request/response protocol.

a. Main components
- Client Module
– SimpleClient (entry point)
– SessionHandler / InstanceHandler
– AbstractRobot and subclass implementations (Recon, Sniper, etc.)
– RequestProtocol, ResponseProtocol
– Client configuration loader
- Server Module
– SimpleServer (entry point)
– ServerService / MultiServers (manages connections)
– RobotHandler (per-connection robot lifecycle)
– World (in-memory grid), ObstacleGenerator, PitsGenerator, Mines
– Command modules (Command, BackCommand, FireCommand, etc.)
– Protocol classes (RequestProtocol, ResponseProtocol)
– ConfigHandler (loads `worlds_config`)
– GUIWorldState (optional visual renderer)
- External Dependencies
– TCP/IP network transport
– `java-turtle` library
– `client_config`, `worlds_config` files

b. Relationships and interactions
1. Client reads `client_config` → initializes SimpleClient → connects to server TCP socket.
2. User or automated robot logic triggers AbstractRobot actions → SessionHandler packages them into RequestProtocol messages → sends over socket.
3. ServerSimple accepts connection → wraps in ServerService → hands off to RobotHandler.
4. RobotHandler parses RequestProtocol → dispatches to Command classes → updates World state (positions, obstacles, mines).
5. ServerService packages world updates into ResponseProtocol → sends back to client.
6. Client SessionHandler parses ResponseProtocol → updates robot’s view → robot logic or UI renders state.

c. Architectural patterns and design principles
- Modular separation: network protocols, command handling, world state, and client logic are cleanly separated into packages.
- Factory/config pattern: `ConfigHandler` decouples configuration from code.
- Command pattern: each robot/server action is encapsulated in a Command class.
- Single Responsibility: World management, protocol serialization, and rendering are in distinct classes.
- In-memory model: No external database, world state lives in memory.

d. Key technologies, frameworks, libraries
- Java 11, Maven multi-module build
- Java sockets for TCP communication
- JUnit for unit tests
- Custom `java-turtle` library for rendering

##### Elements
- Clear component labels (e.g., “Client: SimpleClient,” “Server: SimpleServer”)
- Loading of config files → ConfigHandler
- TCP connections (Client → Server)
- Message flow (RequestProtocol → ResponseProtocol)
- Command dispatch (Protocol → Command classes → World)
- Blue for client-side modules
- Green for server-side modules
- Yellow for shared protocol classes

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Client Side
    subgraph "Client Process"
        direction TB
        CfgClient["client_config"]:::config
        SimpleClient["SimpleClient"]:::client
        SessionHandler["SessionHandler"]:::client
        InstanceHandler["InstanceHandler"]:::client

        subgraph "Client Protocol Layer"
            direction TB
            ReqC["RequestProtocol"]:::protocol
            ResC["ResponseProtocol"]:::protocol
        end

        subgraph "Client Domain Layer"
            direction TB
            AbstractRobot["AbstractRobot"]:::client
            ReconRobot["ReconRobot"]:::client
            SniperRobot["SniperRobot"]:::client
            AssassinRobot["AssassinRobot"]:::client
            SoldierRobot["SoldierRobot"]:::client
        end

        CfgClient -->|loads| SimpleClient
        SimpleClient -->|uses| SessionHandler
        SessionHandler -->|spawns| InstanceHandler
        InstanceHandler -->|sends| ReqC
        ReqC -->|"over TCP"| ResC
        ResC -->|parses| SessionHandler
        SessionHandler -->|updates| AbstractRobot
    end

    %% Network Boundary
    SimpleClient -.->|"TCP Connection"| MultiServers
    ResC -.->|"Response"| SimpleClient

    %% Server Side
    subgraph "Server Process"
        direction TB
        WorldsCfg["worlds_config"]:::config
        LibTurtle["java-turtle-1.0-SNAPSHOT.jar"]:::external
        SimpleServer["SimpleServer"]:::server
        ServerService["ServerService"]:::server
        MultiServers["MultiServers"]:::server
        RobotHandler["RobotHandler"]:::server

        subgraph "Server Infrastructure Layer"
            direction TB
            ConfigHandler["ConfigHandler"]:::server
        end

        subgraph "Server Protocol Layer"
            direction TB
            ReqS["RequestProtocol"]:::protocol
            ResS["ResponseProtocol"]:::protocol
        end

        subgraph "Server Domain Layer"
            direction TB
            World["World"]:::server
            ObstacleGen["ObstacleGenerator"]:::server
            PitsGen["PitsGenerator"]:::server
            Mines["Mines"]:::server
        end

        subgraph "Server Command Layer"
            direction TB
            CommandIface["Command"]:::server
            BackCommand["BackCommand"]:::server
            FireCommand["FireCommand"]:::server
            ForwardCommand["ForwardCommand"]:::server
            LaunchCommand["LaunchCommand"]:::server
            LookCommand["LookCommand"]:::server
            MineCommand["MineCommand"]:::server
            QuitCommand["QuitCommand"]:::server
            ReloadCommand["ReloadCommand"]:::server
            RepairCommand["RepairCommand"]:::server
            StateCommand["StateCommand"]:::server
            TurnCommand["TurnCommand"]:::server
        end

        WorldsCfg -->|loaded by| ConfigHandler -->|initializes| SimpleServer
        SimpleServer -->|binds| MultiServers
        MultiServers -->|accepts| RobotHandler
        RobotHandler -->|parses| ReqS
        ReqS -->|dispatches to| CommandIface
        CommandIface -->|executes on| World
        World -->|state sent via| ResS
        ResS -->|over TCP| ServerService
        ServerService -->|to client| RobotHandler
        LibTurtle -.->|renders| World
    end

    %% Click Events - Client
    click SimpleClient "https://github.com/jayson-aron/robot-worlds/blob/master/client/src/main/java/za/co/wethinkcode/robotworlds/client/SimpleClient.java"
    click SessionHandler "https://github.com/jayson-aron/robot-worlds/blob/master/client/src/main/java/za/co/wethinkcode/robotworlds/client/SessionHandler.java"
    click InstanceHandler "https://github.com/jayson-aron/robot-worlds/blob/master/client/src/main/java/za/co/wethinkcode/robotworlds/client/InstanceHandler.java"
    click AbstractRobot "https://github.com/jayson-aron/robot-worlds/blob/master/client/src/main/java/za/co/wethinkcode/robotworlds/client/AbstractRobot.java"
    click ReconRobot "https://github.com/jayson-aron/robot-worlds/blob/master/client/src/main/java/za/co/wethinkcode/robotworlds/client/ReconRobot.java"
    click SniperRobot "https://github.com/jayson-aron/robot-worlds/blob/master/client/src/main/java/za/co/wethinkcode/robotworlds/client/SniperRobot.java"
    click AssassinRobot "https://github.com/jayson-aron/robot-worlds/blob/master/client/src/main/java/za/co/wethinkcode/robotworlds/client/AssassinRobot.java"
    click SoldierRobot "https://github.com/jayson-aron/robot-worlds/blob/master/client/src/main/java/za/co/wethinkcode/robotworlds/client/SoldierRobot.java"
    click ReqC "https://github.com/jayson-aron/robot-worlds/blob/master/client/src/main/java/za/co/wethinkcode/robotworlds/clientprotocols/RequestProtocol.java"
    click ResC "https://github.com/jayson-aron/robot-worlds/blob/master/client/src/main/java/za/co/wethinkcode/robotworlds/clientprotocols/ResponseProtocol.java"

    %% Click Events - Server
    click SimpleServer "https://github.com/jayson-aron/robot-worlds/blob/master/server/src/main/java/za/co/wethinkcode/robotworlds/server/SimpleServer.java"
    click ServerService "https://github.com/jayson-aron/robot-worlds/blob/master/server/src/main/java/za/co/wethinkcode/robotworlds/server/ServerService.java"
    click MultiServers "https://github.com/jayson-aron/robot-worlds/blob/master/server/src/main/java/za/co/wethinkcode/robotworlds/server/MultiServers.java"
    click RobotHandler "https://github.com/jayson-aron/robot-worlds/blob/master/server/src/main/java/za/co/wethinkcode/robotworlds/server/RobotHandler.java"
    click World "https://github.com/jayson-aron/robot-worlds/blob/master/server/src/main/java/za/co/wethinkcode/robotworlds/server/World.java"
    click ObstacleGen "https://github.com/jayson-aron/robot-worlds/blob/master/server/src/main/java/za/co/wethinkcode/robotworlds/server/ObstacleGenerator.java"
    click PitsGen "https://github.com/jayson-aron/robot-worlds/blob/master/server/src/main/java/za/co/wethinkcode/robotworlds/server/PitsGenerator.java"
    click Mines "https://github.com/jayson-aron/robot-worlds/blob/master/server/src/main/java/za/co/wethinkcode/robotworlds/server/Mines.java"
    click CommandIface "https://github.com/jayson-aron/robot-worlds/blob/master/server/src/main/java/za/co/wethinkcode/robotworlds/server/Command.java"
    click BackCommand "https://github.com/jayson-aron/robot-worlds/blob/master/server/src/main/java/za/co/wethinkcode/robotworlds/server/BackCommand.java"
    click FireCommand "https://github.com/jayson-aron/robot-worlds/blob/master/server/src/main/java/za/co/wethinkcode/robotworlds/server/FireCommand.java"
    click ForwardCommand "https://github.com/jayson-aron/robot-worlds/blob/master/server/src/main/java/za/co/wethinkcode/robotworlds/server/ForwardCommand.java"
    click LaunchCommand "https://github.com/jayson-aron/robot-worlds/blob/master/server/src/main/java/za/co/wethinkcode/robotworlds/server/LaunchCommand.java"
    click LookCommand "https://github.com/jayson-aron/robot-worlds/blob/master/server/src/main/java/za/co/wethinkcode/robotworlds/server/LookCommand.java"
    click MineCommand "https://github.com/jayson-aron/robot-worlds/blob/master/server/src/main/java/za/co/wethinkcode/robotworlds/server/MineCommand.java"
    click QuitCommand "https://github.com/jayson-aron/robot-worlds/blob/master/server/src/main/java/za/co/wethinkcode/robotworlds/server/QuitCommand.java"
    click ReloadCommand "https://github.com/jayson-aron/robot-worlds/blob/master/server/src/main/java/za/co/wethinkcode/robotworlds/server/ReloadCommand.java"
    click RepairCommand "https://github.com/jayson-aron/robot-worlds/blob/master/server/src/main/java/za/co/wethinkcode/robotworlds/server/RepairCommand.java"
    click StateCommand "https://github.com/jayson-aron/robot-worlds/blob/master/server/src/main/java/za/co/wethinkcode/robotworlds/server/StateCommand.java"
    click TurnCommand "https://github.com/jayson-aron/robot-worlds/blob/master/server/src/main/java/za/co/wethinkcode/robotworlds/server/TurnCommand.java"
    click ReqS "https://github.com/jayson-aron/robot-worlds/blob/master/server/src/main/java/za/co/wethinkcode/robotworlds/protocols/RequestProtocol.java"
    click ResS "https://github.com/jayson-aron/robot-worlds/blob/master/server/src/main/java/za/co/wethinkcode/robotworlds/protocols/ResponseProtocol.java"
    click ConfigHandler "https://github.com/jayson-aron/robot-worlds/blob/master/server/src/main/java/za/co/wethinkcode/robotworlds/server/ConfigHandler.java"
    click ObjectSprite "https://github.com/jayson-aron/robot-worlds/blob/master/server/src/main/java/za/co/wethinkcode/robotworlds/server/guiworldstate/ObjectSprite.java"
    click WorldState "https://github.com/jayson-aron/robot-worlds/blob/master/server/src/main/java/za/co/wethinkcode/robotworlds/server/guiworldstate/WorldState.java"

    %% Styles
    classDef client fill:#D0E6FF,stroke:#4A90E2,stroke-width:1px
    classDef server fill:#D5F5E3,stroke:#27AE60,stroke-width:1px
    classDef protocol fill:#FCF3CF,stroke:#F1C40F,stroke-width:1px
    classDef config fill:#E5E8E8,stroke:#95A5A6,stroke-width:1px,stroke-dasharray: 5 5
    classDef infra fill:#EEEEEE,stroke:#7F8C8D,stroke-width:1px
    classDef external fill:#F0F0F0,stroke:#B2BABB,stroke-dasharray: 2 2,stroke-width:1px
```
