# sigmapitech/zappy architecture

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

- Interactive diagram: https://gitdiagram.com/sigmapitech/zappy
- Repository: https://github.com/sigmapitech/zappy

## Overview

##### Project Type and Purpose
- ZAPPY is a full-stack, networked multiplayer game composed of three primary subsystems:
- Server (written in C) – the authoritative game logic and networking engine
- GUI client (written in C++) – a real-time OpenGL/SDL2 visualizer that connects as the “GRAPHIC” team
- AI client (written in Python) – autonomous player agents that connect to the server, parse state, and issue commands
- Additional support components include the “runner” (Python scripts to orchestrate AI teams in CI/testing), developer scripts, documentation, and Nix/flakes build configurations.

##### Key File-Tree Indicators
- Top-level directories:
- ai/ – Python package implementing client logic, communication cipher, async/sync** clients, legacy code
- gui/ – C++ API layers, rendering engine (Demeter), entities, networking, main entrypoint
- server/ – C code organized by client I/O, lifecycle, game events, networking, ring buffer utilities, world management
- runner/ – Python CLI to launch AI processes for automated matches
- scripts/ – Developer tooling for code formatting, header insertion, commit checks
- docs/ – Sphinx/Doxygen documentation for each subsystem and cross-cutting protocols
- Build and configuration: Makefile at root, Doxyfile, flake.nix, CI workflows in .github/workflows.

- Server Core (red)
- Network Listener / TCP Acceptor
- Client Manager
- Game Logic Engine (world grid, resource spawner, event queue)
- Protocol Validator / Command Executor
- Broadcast Propagation Service
- AI Clients (green)
- Command Manager + Async/Sync Client
- Message Cipher Module
- Behavior Engine (parsing look/inventory, deciding moves)
- GUI Client (green)
- Network Module (same protocol, reserved “GRAPHIC” team)
- Rendering Engine (Demeter, OpenGL/SDL2)
- Entities & Sub-window Manager
- Runner & CI Tools (blue)
- Python orchestration to spin up multiple AI clients
- Test harness invoking server and validating game outcomes
- Developer Scripts & Build System (gray)
- Makefile, Doxygen, Nix flakes, commit-hook scripts

- AI Clients →← Server Core over TCP sockets (exchange textual protocol commands and state updates)
- GUI Client →← Server Core over TCP (push-based updates → renderer)
- Server Core internal: Network Listener → Client Manager → Game Logic → Broadcast Service → Network I/O
- Runner orchestrates spawning of Server Core and multiple AI Clients; collects logs and metrics
- CI Workflows trigger tests against each subsystem (ai, gui, server)

c. Architectural Patterns and Principles
- Modular separation: network I/O, game logic, client logic, rendering decoupled into their own modules
- Event queue pattern on server for ordered player actions and world updates
- Client-Server protocol layer common to both AI and GUI (“GRAPHIC” is just a reserved team name)
- Use of asynchronous messaging in AI module vs. event-driven redraws in GUI for performance

d. Technologies and Frameworks
- Server: plain C, POSIX sockets, custom ring buffers, Makefile build
- GUI: C++17, SDL2, OpenGL, ImGui, custom asset loaders (.obj3D, GLSL shaders)
- AI & Runner: Python3, asyncio, custom cipher, pyproject.toml for dependencies
- DevOps: Nix/flakes, CI via GitHub Actions

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Server Layer
    subgraph "Server Core"
        direction TB
        netListener["Network Listener / TCP Acceptor"]:::server
        clientManager["Client Manager"]:::server
        gameLogic["Game Logic Engine"]:::server
        protocolValidator["Protocol Validator / Command Executor"]:::server
        broadcastService["Broadcast Propagation Service"]:::server
    end

    %% Clients Layer
    subgraph "Clients"
        direction TB
        subgraph "AI Clients"
            direction TB
            aiCmdMgr["Command Manager + Async/Sync Client"]:::client
            aiCipher["Message Cipher Module"]:::client
            aiBehavior["Behavior Engine"]:::client
            aiLegacy["Legacy Code Paths"]:::client
        end
        subgraph "GUI Client"
            direction TB
            guiNet["Network Module"]:::client
            guiRender["Rendering Engine (Demeter)"]:::client
            guiEntities["Entities & Sub-window Manager"]:::client
        end
    end

    %% Runner/CI Layer
    subgraph "Runner & CI Tools"
        direction TB
        runnerCLI["AI Orchestration CLI"]:::orchestration
        runnerTeam["Team Names & Pool Management"]:::orchestration
        runnerPool["Binpool Module"]:::orchestration
        subgraph "CI Workflows"
            direction TB
            ci1["ci.yml"]:::orchestration
            ci2["cov.yml"]:::orchestration
            ci3["doc.yml"]:::orchestration
        end
    end

    %% Developer Scripts Layer
    subgraph "Developer & Build"
        direction TB
        makefile["Makefile"]:::dev
        doxy["Doxyfile"]:::dev
        flake["flake.nix"]:::dev
        scriptsDir["scripts/"]:::dev
    end

    %% Internal Server Flow
    netListener -->|accepts TCP| clientManager
    clientManager -->|dispatch| gameLogic
    gameLogic -->|enqueue events| broadcastService
    broadcastService -->|propagate| netListener

    %% Client-Server Communication
    aiCmdMgr <-->|TCP Protocol| netListener
    guiNet <-->|TCP Protocol| netListener

    %% Runner Orchestration
    runnerCLI -->|spawns| netListener
    runnerCLI -->|spawns| aiCmdMgr
    runnerCLI -->|spawns| guiNet
    runnerCLI -->|collects logs| runnerCLI

    %% CI Triggers
    ci1 -->|tests| aiCmdMgr
    ci1 -->|tests| guiNet
    ci1 -->|tests| netListener
    ci2 -->|coverage| aiCmdMgr
    ci3 -->|docs| doxy

    %% Developer Scripts Dependencies
    makefile --> netListener
    flake --> aiCmdMgr
    flake --> guiNet
    scriptsDir --> makefile

    %% Click Events
    click netListener "https://github.com/sigmapitech/zappy/blob/dev/server/network_handle_event.c"
    click clientManager "https://github.com/sigmapitech/zappy/blob/dev/server/client/client_manager.c"
    click gameLogic "https://github.com/sigmapitech/zappy/blob/dev/server/game_queue_events.c"
    click protocolValidator "https://github.com/sigmapitech/zappy/blob/dev/server/client/client_command_split.c"
    click broadcastService "https://github.com/sigmapitech/zappy/blob/dev/server/game_events/player_broadcast.c"
    click aiCmdMgr "https://github.com/sigmapitech/zappy/blob/dev/ai/crow/command_manager.py"
    click aiCipher "https://github.com/sigmapitech/zappy/blob/dev/ai/cipher.py"
    click aiBehavior "https://github.com/sigmapitech/zappy/blob/dev/ai/player.py"
    click aiLegacy "https://github.com/sigmapitech/zappy/tree/dev/ai/legacy/"
    click guiNet "https://github.com/sigmapitech/zappy/blob/dev/gui/Network/Network.cpp"
    click guiNet "https://github.com/sigmapitech/zappy/blob/dev/gui/Network/Network.hpp"
    click guiRender "https://github.com/sigmapitech/zappy/blob/dev/gui/Demeter/Demeter.cpp"
    click guiRender "https://github.com/sigmapitech/zappy/tree/dev/gui/Demeter/Renderer/"
    click guiEntities "https://github.com/sigmapitech/zappy/blob/dev/gui/Entities/SubWindowHandler.cpp"
    click guiEntities "https://github.com/sigmapitech/zappy/blob/dev/gui/Entities/*.hpp"
    click runnerCLI "https://github.com/sigmapitech/zappy/blob/dev/runner/zappy/run.py"
    click runnerTeam "https://github.com/sigmapitech/zappy/blob/dev/runner/zappy/team_names.py"
    click runnerPool "https://github.com/sigmapitech/zappy/blob/dev/runner/zappy/binpool.py"
    click ci1 "https://github.com/sigmapitech/zappy/blob/dev/.github/workflows/ci.yml"
    click ci2 "https://github.com/sigmapitech/zappy/blob/dev/.github/workflows/cov.yml"
    click ci3 "https://github.com/sigmapitech/zappy/blob/dev/.github/workflows/doc.yml"
    click makefile "https://github.com/sigmapitech/zappy/tree/dev/Makefile"
    click doxy "https://github.com/sigmapitech/zappy/tree/dev/Doxyfile"
    click flake "https://github.com/sigmapitech/zappy/blob/dev/flake.nix"
    click scriptsDir "https://github.com/sigmapitech/zappy/tree/dev/scripts/"

    %% Styles
    classDef server fill:#f88,stroke:#800,stroke-width:1px;
    classDef client fill:#8f8,stroke:#080,stroke-width:1px;
    classDef orchestration fill:#88f,stroke:#008,stroke-width:1px;
    classDef dev fill:#ccc,stroke:#666,stroke-width:1px;
```
