# etrl-z/ciociariaguerrabot architecture

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

- Interactive diagram: https://gitdiagram.com/etrl-z/ciociariaguerrabot
- Repository: https://github.com/etrl-z/ciociariaguerrabot

## Overview

Ciociaria Guerra Bot simulates territorial conquest among Frosinone municipalities. The batch runner selects a municipality according to Short or Long mode, delegates each turn to the game engine, and repeats until a winner remains; the replay runner instead loads a saved extraction history and replays it. Conquest logic resolves attackers and targets, transfers ownership, and recalculates territorial centers. The engine renders turn and victory maps and uploads them to Firestore. The README also documents optional GIF creation, represented as a capability, though no caller is shown. Relationships are limited to excerpted calls and README statements.

Main entry points: [`CiociariaGuerraBot.Core/GameEngine.cs`](https://github.com/etrl-z/ciociariaguerrabot/blob/master/CiociariaGuerraBot.Core/GameEngine.cs) (Turn engine), [`CiociariaGuerraBot.Core/MapRenderer.cs`](https://github.com/etrl-z/ciociariaguerrabot/blob/master/CiociariaGuerraBot.Core/MapRenderer.cs) (Map renderer), [`CiociariaGuerraBot.Core/FirebaseClient.cs`](https://github.com/etrl-z/ciociariaguerrabot/blob/master/CiociariaGuerraBot.Core/FirebaseClient.cs) (Firestore client), [`CiociariaGuerraBot.Batch/Program.cs`](https://github.com/etrl-z/ciociariaguerrabot/blob/master/CiociariaGuerraBot.Batch/Program.cs) (Batch runner)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_execution["Game execution"]
  node_batch["Batch runner<br/>[Program.cs]"]
  node_replay["Replay runner<br/>[Program.cs]"]
  node_engine["Turn engine<br/>[GameEngine.cs]"]
end

subgraph group_domain["Conquest domain"]
  node_rules["Conquest rules<br/>[Utilities.cs]"]
  node_municipality["Municipality state<br/>[Municipality.cs]"]
end

subgraph group_presentation["Maps and media"]
  node_map["SVG map input"]
  node_renderer["Map renderer<br/>[MapRenderer.cs]"]
  node_image["SVG-to-JPG conversion<br/>[Utilities.cs]"]
  node_gif["Optional GIF maker<br/>[GifMaker.cs]"]
end

subgraph group_persistence["Persistence and logging"]
  node_firebase["Firestore client<br/>[FirebaseClient.cs]"]
  node_firestore[("Firestore")]
  node_logger["Run logger<br/>[Logger.cs]"]
end

node_operator(("Operator"))

node_operator -.->|"starts game"| node_batch
node_operator -.->|"starts replay"| node_replay
node_batch -->|"loads map"| node_renderer
node_batch -->|"finds active"| node_rules
node_batch -->|"plays turns"| node_engine
node_replay -->|"loads map"| node_renderer
node_replay -->|"loads history"| node_firebase
node_replay -->|"replays turns"| node_engine
node_engine -->|"resolves conquest"| node_rules
node_engine -->|"renders turn"| node_renderer
node_engine -->|"uploads image"| node_firebase
node_engine -->|"records victory"| node_firebase
node_engine -->|"logs events"| node_logger
node_rules -->|"updates ownership"| node_municipality
node_rules -->|"logs conquest"| node_logger
node_renderer -->|"loads SVG"| node_map
node_renderer -->|"creates records"| node_municipality
node_renderer -->|"converts output"| node_image
node_renderer -->|"logs issues"| node_logger
node_firebase -->|"reads and writes"| node_firestore
node_firebase -->|"logs victory"| node_logger
node_gif -->|"converts frames"| node_image

click node_batch "https://github.com/etrl-z/ciociariaguerrabot/blob/master/CiociariaGuerraBot.Batch/Program.cs"
click node_replay "https://github.com/etrl-z/ciociariaguerrabot/blob/master/CiociariaGuerraBot.Replay/Program.cs"
click node_engine "https://github.com/etrl-z/ciociariaguerrabot/blob/master/CiociariaGuerraBot.Core/GameEngine.cs"
click node_rules "https://github.com/etrl-z/ciociariaguerrabot/blob/master/CiociariaGuerraBot.Core/Utilities.cs"
click node_municipality "https://github.com/etrl-z/ciociariaguerrabot/blob/master/CiociariaGuerraBot.Core/Municipality.cs"
click node_renderer "https://github.com/etrl-z/ciociariaguerrabot/blob/master/CiociariaGuerraBot.Core/MapRenderer.cs"
click node_image "https://github.com/etrl-z/ciociariaguerrabot/blob/master/CiociariaGuerraBot.Core/Utilities.cs"
click node_gif "https://github.com/etrl-z/ciociariaguerrabot/blob/master/CiociariaGuerraBot.Core/GifMaker.cs"
click node_firebase "https://github.com/etrl-z/ciociariaguerrabot/blob/master/CiociariaGuerraBot.Core/FirebaseClient.cs"
click node_logger "https://github.com/etrl-z/ciociariaguerrabot/blob/master/CiociariaGuerraBot.Core/Logger.cs"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_batch,node_replay,node_engine toneBlue
class node_rules,node_municipality toneAmber
class node_map,node_renderer,node_image,node_gif toneMint
class node_firebase,node_firestore,node_logger toneRose
class node_operator toneIndigo
```

## Components

### Game execution

- [Batch runner](https://github.com/etrl-z/ciociariaguerrabot/blob/master/CiociariaGuerraBot.Batch/Program.cs): `CiociariaGuerraBot.Batch/Program.cs`
- [Replay runner](https://github.com/etrl-z/ciociariaguerrabot/blob/master/CiociariaGuerraBot.Replay/Program.cs): `CiociariaGuerraBot.Replay/Program.cs`
- [Turn engine](https://github.com/etrl-z/ciociariaguerrabot/blob/master/CiociariaGuerraBot.Core/GameEngine.cs): `CiociariaGuerraBot.Core/GameEngine.cs`

### Conquest domain

- [Conquest rules](https://github.com/etrl-z/ciociariaguerrabot/blob/master/CiociariaGuerraBot.Core/Utilities.cs): `CiociariaGuerraBot.Core/Utilities.cs`
- [Municipality state](https://github.com/etrl-z/ciociariaguerrabot/blob/master/CiociariaGuerraBot.Core/Municipality.cs): `CiociariaGuerraBot.Core/Municipality.cs`

### Maps and media

- **SVG map input**
- [Map renderer](https://github.com/etrl-z/ciociariaguerrabot/blob/master/CiociariaGuerraBot.Core/MapRenderer.cs): `CiociariaGuerraBot.Core/MapRenderer.cs`
- [SVG-to-JPG conversion](https://github.com/etrl-z/ciociariaguerrabot/blob/master/CiociariaGuerraBot.Core/Utilities.cs): `CiociariaGuerraBot.Core/Utilities.cs`
- [Optional GIF maker](https://github.com/etrl-z/ciociariaguerrabot/blob/master/CiociariaGuerraBot.Core/GifMaker.cs): `CiociariaGuerraBot.Core/GifMaker.cs`

### Persistence and logging

- [Firestore client](https://github.com/etrl-z/ciociariaguerrabot/blob/master/CiociariaGuerraBot.Core/FirebaseClient.cs): `CiociariaGuerraBot.Core/FirebaseClient.cs`
- **Firestore**
- [Run logger](https://github.com/etrl-z/ciociariaguerrabot/blob/master/CiociariaGuerraBot.Core/Logger.cs): `CiociariaGuerraBot.Core/Logger.cs`

### Other components

- **Operator**

## Connections

- Operator → Batch runner: starts game
- Operator → Replay runner: starts replay
- Batch runner → Map renderer: loads map (evidence: `CiociariaGuerraBot.Batch/Program.cs`)
- Batch runner → Conquest rules: finds active (evidence: `CiociariaGuerraBot.Batch/Program.cs`)
- Batch runner → Turn engine: plays turns (evidence: `CiociariaGuerraBot.Batch/Program.cs`)
- Replay runner → Map renderer: loads map (evidence: `CiociariaGuerraBot.Replay/Program.cs`)
- Replay runner → Firestore client: loads history (evidence: `CiociariaGuerraBot.Replay/Program.cs`)
- Replay runner → Turn engine: replays turns (evidence: `CiociariaGuerraBot.Replay/Program.cs`)
- Turn engine → Conquest rules: resolves conquest (evidence: `CiociariaGuerraBot.Core/GameEngine.cs`)
- Turn engine → Map renderer: renders turn (evidence: `CiociariaGuerraBot.Core/GameEngine.cs`)
- Turn engine → Firestore client: uploads image (evidence: `CiociariaGuerraBot.Core/GameEngine.cs`)
- Turn engine → Firestore client: records victory (evidence: `CiociariaGuerraBot.Core/GameEngine.cs`)
- Turn engine → Run logger: logs events (evidence: `CiociariaGuerraBot.Core/GameEngine.cs`)
- Conquest rules → Municipality state: updates ownership (evidence: `CiociariaGuerraBot.Core/Utilities.cs`)
- Conquest rules → Run logger: logs conquest (evidence: `CiociariaGuerraBot.Core/Utilities.cs`)
- Map renderer → SVG map input: loads SVG (evidence: `CiociariaGuerraBot.Core/MapRenderer.cs`)
- Map renderer → Municipality state: creates records (evidence: `CiociariaGuerraBot.Core/MapRenderer.cs`)
- Map renderer → SVG-to-JPG conversion: converts output (evidence: `CiociariaGuerraBot.Core/MapRenderer.cs`)
- Map renderer → Run logger: logs issues (evidence: `CiociariaGuerraBot.Core/MapRenderer.cs`)
- Firestore client → Firestore: reads and writes (evidence: `README.md`)
- Firestore client → Run logger: logs victory (evidence: `CiociariaGuerraBot.Core/FirebaseClient.cs`)
- Optional GIF maker → SVG-to-JPG conversion: converts frames (evidence: `CiociariaGuerraBot.Core/GifMaker.cs`)
