# goodstartlabs/ai_diplomacy architecture

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

- Interactive diagram: https://gitdiagram.com/goodstartlabs/ai_diplomacy
- Repository: https://github.com/goodstartlabs/ai_diplomacy

## Overview

##### Project Type and Purpose
- This is a full-stack, AI-powered extension of a turn-based board game (“Diplomacy”) combining:
- A Python core game engine (`diplomacy` package)
- An AI layer of stateful agents powered by LLMs (`ai_diplomacy` package + CLI orchestrators)
- Analysis pipelines (`analysis/`, `experiment_runner/analysis/`)
- Interactive visualizations:
– 3D animation front-end (`ai_animation/` with Vite/TypeScript)
– React web UI (`diplomacy/web/`)
- Deployment support via Docker and docker-compose

##### File Structure
- Top-level Python modules and CLI scripts:
- `diplomacy/` – core engine, network client, server, maps, utils, web backend
- `ai_diplomacy/` – AI agent implementation, LLM client abstractions, prompt templates
- Orchestrators: `lm_game.py`, `experiment_runner.py`, plus `analysis/`, `experiments/`
- Front-end:
- `diplomacy/web/` – React app for human play and visualization of games
- `ai_animation/` – standalone 3D playback UI
- Config/deployment:
- `.env.example`, `docker-compose.yaml`, Dockerfiles in subdirs
- Data:
- `results/` directories written at runtime (JSON, CSV, logs)
- Analysis notebooks and scripts reading those results

##### Extract Key Insights from README
- Core engine is a Python library managing game state, map logic, server/client APIs
- `ai_diplomacy` agents wrap the engine, track memory, build LLM prompts, call LLMs for decisions
- CLI tools (`lm_game.py`, `experiment_runner.py`) orchestrate game loops, batch experiments, and launch analysis modules
- Data flow: engine + agents → LLM calls → orders & messages → engine processes next phase → logs & results written → post-game analysis and visualization

##### Main Components & Interactions
a. Components
- Core Game Engine (diplomacy package)
- AI Agent Layer (ai_diplomacy modules)
- Orchestrators (lm_game.py, experiment_runner.py)
- External LLM Services (OpenAI, Claude, Gemini, etc.)
- Data Store (results directory, JSON/CSV files)
- Analysis Pipelines (analysis/, experiment_runner/analysis/)
- 3D Animation Front-end (ai_animation/)
- Web UI & Server (diplomacy/web/ + diplomacy.server)
- Deployment & CI (Docker, GitHub workflows)

b. Relationships & Data Flow
1. **Orchestrator (lm_game)**
– Invokes Core Engine to initialize game state
– Instantiates one DiplomacyAgent per power (ai_diplomacy.agent)
– In each phase:
- Gathers game state from Core Engine
- Agent builds prompt via PromptConstructor → calls LLM Client → receives decision
- Submits orders/messages back to engine → engine processes phase
- Writes phase summary & agent state to Results (JSON, logs, llm_responses.csv)
2. **Experiment Runner**
– Launches multiple `lm_game` instances in parallel
– Aggregates runs under an experiment directory
– Triggers Analysis Pipelines upon completion
3. **Analysis Pipelines**
– Read Result files → generate RL JSON → statistical reports, lie detection, moment analysis
4. **Visualization & Web UI**
– 3D Animation reads saved game JSON → interactive playback
– React Web UI connects via WebSocket/HTTP to `diplomacy.server` → real-time game view & human players
5. **External LLM Services**
– `ai_diplomacy/clients` call third-party APIs → return structured replies → Agent updates memory

c. Architectural Patterns & Design Principles
– Modular layered design:
- Engine layer (core game logic)
- AI layer (agents, prompt templates)
- Orchestration/CLI layer
- Data analysis layer
- Presentation/UI layers
– Separation of concerns: engine is independent of AI, which is independent of UI
– Plugin-style LLM client abstraction (supports multiple providers)
– Batch orchestration via ExperimentRunner using process pools
– File-based persistence for reproducibility

d. Technologies & Frameworks
– Python 3.10+ with `uv` for env management
– LLM APIs (OpenAI, Anthropic, Gemini, DeepSeek, OpenRouter)
– TypeScript + Vite for 3D animation
– React for web UI
– Docker & docker-compose for containerization
– Playwright & Vitest for testing front-ends
– Sphinx for API docs

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Backend Layer
    subgraph "Backend Layer"
        CoreEngine["Core Game Engine"]:::backend
        NetworkClient["Network Client"]:::backend
        NetworkServer["Network Server"]:::backend
        MapLogic["Map Logic & Assets"]:::backend
        AIAgent["AI Agent Layer"]:::ai
        LLMClients["LLM Client Abstractions"]:::ai
        PromptTemplates["Prompt Templates"]:::ai
        Orchestrator["CLI Orchestrator (lm_game.py)"]:::backend
        ExperimentRunner["Experiment Runner"]:::backend
        GeneralAnalysis["General Analysis Pipelines"]:::backend
        ExpAnalysis["Experiment Runner Analysis"]:::backend
        GameServer["Game Server"]:::backend
    end

    %% External Services
    subgraph "External Services"
        LLMServices["External LLM Services"]:::external
    end

    %% Data Store
    subgraph "Data Store"
        Results["Data Store (Results & Logs)"]:::data
    end

    %% Front-end Layer
    subgraph "Front-end"
        Animation3D["3D Animation UI"]:::frontend
        WebUI["React Web UI"]:::frontend
    end

    %% Deployment & Documentation
    subgraph "Deployment & CI"
        DockerCompose["Docker Compose"]:::deploy
        GitHubCI["GitHub Workflows"]:::deploy
        Dockerfile1["ai_animation Dockerfile"]:::deploy
        Dockerfile2["twitch-streamer Dockerfile"]:::deploy
        APIDocs["API Documentation (Sphinx)"]:::deploy
    end

    %% Orchestration Loop
    Orchestrator -->|init game state| CoreEngine
    Orchestrator -->|instantiate agents| AIAgent
    CoreEngine -->|provide state| Orchestrator
    Orchestrator -->|request decision| AIAgent
    AIAgent -->|build prompt| PromptTemplates
    AIAgent -->|call LLM| LLMClients
    LLMClients -->|API call| LLMServices
    LLMServices -->|response| LLMClients
    LLMClients -->|decision| AIAgent
    AIAgent -->|submit orders| CoreEngine
    CoreEngine -->|phase results| Orchestrator
    Orchestrator -->|write logs| Results

    %% Experiment Runner
    ExperimentRunner -->|launch multiple| Orchestrator
    ExperimentRunner -->|aggregate runs| Results
    ExperimentRunner -->|trigger analysis| ExpAnalysis
    ExpAnalysis -->|read results| Results

    %% General Analysis
    GeneralAnalysis -->|read results| Results

    %% Front-end Data Flow
    Animation3D -->|read game JSON| Results
    WebUI -->|real-time updates| GameServer
    GameServer -->|connect| CoreEngine
    WebUI -->|fetch saved games| Results

    %% Deployment Connections
    DockerCompose -->|orchestrates| CoreEngine
    DockerCompose -->|orchestrates| AIAgent
    DockerCompose -->|orchestrates| WebUI
    GitHubCI -->|CI pipelines| DockerCompose
    Dockerfile1 -->|build| Animation3D
    Dockerfile2 -->|build| WebUI
    APIDocs -->|docs for| CoreEngine

    %% Click Events
    click CoreEngine "https://github.com/goodstartlabs/ai_diplomacy/tree/main/diplomacy/engine/"
    click NetworkClient "https://github.com/goodstartlabs/ai_diplomacy/tree/main/diplomacy/client/"
    click NetworkServer "https://github.com/goodstartlabs/ai_diplomacy/tree/main/diplomacy/server/"
    click MapLogic "https://github.com/goodstartlabs/ai_diplomacy/tree/main/diplomacy/maps/"
    click AIAgent "https://github.com/goodstartlabs/ai_diplomacy/blob/main/ai_diplomacy/agent.py"
    click LLMClients "https://github.com/goodstartlabs/ai_diplomacy/blob/main/ai_diplomacy/clients.py"
    click PromptTemplates "https://github.com/goodstartlabs/ai_diplomacy/tree/main/ai_diplomacy/prompts/"
    click Orchestrator "https://github.com/goodstartlabs/ai_diplomacy/blob/main/lm_game.py"
    click ExperimentRunner "https://github.com/goodstartlabs/ai_diplomacy/blob/main/experiment_runner.py"
    click GeneralAnalysis "https://github.com/goodstartlabs/ai_diplomacy/tree/main/analysis/"
    click ExpAnalysis "https://github.com/goodstartlabs/ai_diplomacy/tree/main/experiment_runner/analysis/"
    click Animation3D "https://github.com/goodstartlabs/ai_diplomacy/tree/main/ai_animation/"
    click WebUI "https://github.com/goodstartlabs/ai_diplomacy/tree/main/diplomacy/web/"
    click Results "https://github.com/goodstartlabs/ai_diplomacy/tree/main/visualization_results/"
    click DockerCompose "https://github.com/goodstartlabs/ai_diplomacy/blob/main/docker-compose.yaml"
    click GitHubCI "https://github.com/goodstartlabs/ai_diplomacy/tree/main/.github/workflows/"
    click Dockerfile1 "https://github.com/goodstartlabs/ai_diplomacy/tree/main/ai_animation/Dockerfile"
    click Dockerfile2 "https://github.com/goodstartlabs/ai_diplomacy/tree/main/twitch-streamer/Dockerfile"
    click APIDocs "https://github.com/goodstartlabs/ai_diplomacy/tree/main/docs/api/"

    %% Styles
    classDef backend fill:#D6EAF8,stroke:#2980B9,color:#154360
    classDef ai fill:#D5F5E3,stroke:#27AE60,color:#186A3B
    classDef external fill:#FAD7A0,stroke:#D68910,color:#935116
    classDef data fill:#FCF3CF,stroke:#B7950B,color:#7E5109
    classDef frontend fill:#F5EEF8,stroke:#8E44AD,color:#512E5F
    classDef deploy fill:#E5E7E9,stroke:#566573,color:#2C3E50
```
