# norinorin/wordgames architecture

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

- Interactive diagram: https://gitdiagram.com/norinorin/wordgames
- Repository: https://github.com/norinorin/wordgames

## Overview

##### Project Type and Purpose
- This is a Rust-based server for word games (the anagrams game is explicitly mentioned). It is based on a port of a Java implementation and interacts with a client (such as PixelSam123’s client). The project retrieves a word bank from an external API (Datamuse).
- The project is organized as a backend server application that utilizes WebSocket connections for gameplay (as indicated by the “wss://…” URL in the README).

##### Main Components
a. Server Core:
- The central entry point is in src/main.rs. This represents the application’s runtime which initiates the server.
b. Command and Handler Modules:
- Commands: Located under src/commands (with files like help.rs, score.rs, start.rs) which implement the business logic for different game commands.
- Handlers: Under src/handlers (with command_handler.rs, ws_handlers.rs) which are responsible for processing incoming client messages over WebSocket and dispatching them to the appropriate command modules.
c. Game Logic Modules:
- The anagram game logic is defined in src/anagram.rs.
- Application state is handled in src/app_state.rs, likely maintaining the state of ongoing games or user sessions.
d. Message Definitions:
- src/server_message.rs likely defines the structure of outbound messages or events.
e. External Interactions:
- Word bank retrieval from Datamuse API (this isn’t visible as a specific module but is mentioned in the README and likely integrated within the command or game logic modules).
f. Supporting Scripts:
- The scripts directory contains scripts/client.py, which may be used as a testing or demonstration client to interact with the server.

##### Relationships and Interactions
- Incoming WebSocket connections (from external clients) are received by the server (src/main.rs), which then forwards them to the ws_handlers in src/handlers/ws_handlers.rs.
- The command_handler (found in src/handlers/command_handler.rs and aggregated by src/handlers/mod.rs) intercepts the incoming commands and dispatches them to the appropriate sub-modules under src/commands/.
- Commands (such as start, score, and help) process the client’s input. They utilize the shared game logic (like the anagram functionality in src/anagram.rs) and interact with the application state (in src/app_state.rs).
- The responses or game updates are then formulated as server messages (documented in src/server_message.rs) and sent back to the client.
- The client script (scripts/client.py) can be visualized as an external actor used for demonstration or testing.

##### Architectural Patterns and Design Principles
- Modularity: The commands and handlers are separated into their own directories, showcasing a modular design that isolates responsibilities.
- Clearly delineated layers: There is a layer that handles incoming communications (handlers), a processing layer (commands, anagram logic, app state), and the messaging/output layer (server message).
- Separation of concerns: Different modules handle different aspects (e.g., a dedicated module for state management, separate modules for different commands).

##### Specific Elements
- Clear labels for each component: Label core components (Server Core, Handlers, Commands, Game Logic, App State, External API, Client).
- Annotations: Add annotations to indicate the interactions such as “Incoming WebSocket Connection”, “Command Dispatch”, “State Update”, “API Query”, and “Response to Client”.

## Diagram (Mermaid)

```mermaid
flowchart TD
    Client("Client"):::external
    ClientScript("Client Script"):::external
    ServerCore("Server Core"):::core
    WsHandlers("WS Handlers"):::handler
    CommandHandler("Command Handler"):::handler
    ServerMessage("Server Message"):::message
    ExternalAPI("External API: Datamuse"):::api

    subgraph "Command Modules"
        StartCommand("Start Command"):::command
        ScoreCommand("Score Command"):::command
        HelpCommand("Help Command"):::command
    end

    subgraph "Game Logic & State"
        AnagramLogic("Anagram Logic"):::logic
        AppState("Application State"):::logic
    end

    Client -->|"WSConnection"| ServerCore
    ClientScript -->|"TestWS"| ServerCore

    ServerCore -->|"forwardsWS"| WsHandlers
    WsHandlers -->|"dispatches"| CommandHandler

    CommandHandler -->|"dispatch"| StartCommand
    CommandHandler -->|"dispatch"| ScoreCommand
    CommandHandler -->|"dispatch"| HelpCommand

    StartCommand -->|"calls"| AnagramLogic
    StartCommand -->|"updates"| AppState
    ScoreCommand -->|"calls"| AnagramLogic
    ScoreCommand -->|"updates"| AppState
    HelpCommand -->|"calls"| AnagramLogic
    HelpCommand -->|"updates"| AppState

    CommandHandler -->|"formsResponse"| ServerMessage
    ServerMessage -->|"sendsResponse"| Client

    AnagramLogic -->|"queriesWordBank"| ExternalAPI

    click ServerCore "https://github.com/norinorin/wordgames/blob/main/src/main.rs"
    click WsHandlers "https://github.com/norinorin/wordgames/blob/main/src/handlers/ws_handlers.rs"
    click CommandHandler "https://github.com/norinorin/wordgames/blob/main/src/handlers/command_handler.rs"
    click StartCommand "https://github.com/norinorin/wordgames/blob/main/src/commands/start.rs"
    click ScoreCommand "https://github.com/norinorin/wordgames/blob/main/src/commands/score.rs"
    click HelpCommand "https://github.com/norinorin/wordgames/blob/main/src/commands/help.rs"
    click AnagramLogic "https://github.com/norinorin/wordgames/blob/main/src/anagram.rs"
    click AppState "https://github.com/norinorin/wordgames/blob/main/src/app_state.rs"
    click ServerMessage "https://github.com/norinorin/wordgames/blob/main/src/server_message.rs"
    click ClientScript "https://github.com/norinorin/wordgames/blob/main/scripts/client.py"

    classDef external fill:#FFD700,stroke:#333,stroke-width:2px;
    classDef core fill:#8FBC8F,stroke:#333,stroke-width:2px;
    classDef handler fill:#ADD8E6,stroke:#333,stroke-width:2px;
    classDef command fill:#FFA07A,stroke:#333,stroke-width:2px;
    classDef logic fill:#98FB98,stroke:#333,stroke-width:2px;
    classDef api fill:#FF9999,stroke:#333,stroke-width:2px;
    classDef message fill:#DDA0DD,stroke:#333,stroke-width:2px;
```
