# devzero32/factionmapv4 architecture

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

- Interactive diagram: https://gitdiagram.com/devzero32/factionmapv4
- Repository: https://github.com/devzero32/factionmapv4

## Overview

FactionMapv4 is a Discord-hosted faction strategy game: players use bot commands to establish factions and manage armies, regions, resources, and battles, while scheduled turns advance the game and the bot presents map imagery and notifications. The sampled code shows command dispatch, JSON-backed game state, and several domain-handler responsibilities; README documentation is minimal, and unsampled command wiring is not inferred.

Main entry points: [`Imports/jsonhandler.py`](https://github.com/devzero32/factionmapv4/blob/main/Imports/jsonhandler.py) (JSON access), [`main.py`](https://github.com/devzero32/factionmapv4/blob/main/main.py) (Command bot), [`Imports/factionshandler.py`](https://github.com/devzero32/factionmapv4/blob/main/Imports/factionshandler.py) (Faction management), [`Imports/regionhandler.py`](https://github.com/devzero32/factionmapv4/blob/main/Imports/regionhandler.py) (Region operations)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Discord interface"]
  node_bot["Command bot<br/>[main.py]"]
  node_admin["Admin and logs<br/>[adminhandler.py]"]
end

subgraph group_game["Game systems"]
  node_factions["Faction management<br/>[factionshandler.py]"]
  node_armies["Army operations<br/>[armyhandler.py]"]
  node_regions["Region operations<br/>[regionhandler.py]"]
  node_economy["Trade economy<br/>[economyHandler.py]"]
  node_turns["Turn scheduler<br/>[turnshandler.py]"]
  node_battles["Battle mediation<br/>[mediatorhandler.py]"]
  node_models["Game models<br/>[classhandler.py]"]
end

subgraph group_state["Game state"]
  node_json["JSON access<br/>[jsonhandler.py]"]
  node_factiondata["Faction records<br/>[factions.json]"]
  node_regiondata["Region records<br/>[regions.json]"]
  node_turnstate["Turn records<br/>[turns.json]"]
  node_battledata["Battle records<br/>[mediator.json]"]
  node_tradedata["Trade records<br/>[trades.json]"]
end

subgraph group_presentation["Presentation"]
  node_map["Map rendering<br/>[imagehandler.py]"]
  node_images["Map assets"]
  node_logos["Faction logos"]
  node_embeds["Response embeds<br/>[embedhandler.py]"]
end

node_players(("Faction players"))
node_discord(("Discord platform"))

node_players -->|"issue commands"| node_discord
node_discord -->|"deliver interactions"| node_bot
node_bot -->|"send responses"| node_discord
node_bot -->|"dispatch setup"| node_factions
node_bot -->|"dispatch army actions"| node_armies
node_bot -->|"dispatch region actions"| node_regions
node_bot -->|"start turn sequence"| node_turns
node_bot -->|"dispatch battle actions"| node_battles
node_bot -->|"log commands"| node_admin
node_factions -->|"read and update"| node_json
node_armies -->|"read and update"| node_json
node_regions -->|"read and update"| node_json
node_economy -->|"read and update"| node_json
node_turns -->|"read and update"| node_json
node_battles -->|"read battle state"| node_json
node_models -->|"load game data"| node_json
node_json -->|"read and write"| node_factiondata
node_json -->|"read and write"| node_regiondata
node_json -->|"read and write"| node_turnstate
node_battles -->|"read and write"| node_battledata
node_economy -->|"manage trades"| node_tradedata
node_turns -->|"distribute trades"| node_economy
node_regions -->|"update borders and buildings"| node_map
node_map -->|"load map assets"| node_images
node_factions -->|"save and use logos"| node_logos
node_map -->|"provide map output"| node_bot
node_factions -->|"format responses"| node_embeds
node_armies -->|"format responses"| node_embeds
node_regions -->|"format responses"| node_embeds
node_admin -->|"check roles"| node_discord

click node_bot "https://github.com/devzero32/factionmapv4/blob/main/main.py"
click node_factions "https://github.com/devzero32/factionmapv4/blob/main/Imports/factionshandler.py"
click node_armies "https://github.com/devzero32/factionmapv4/blob/main/Imports/armyhandler.py"
click node_regions "https://github.com/devzero32/factionmapv4/blob/main/Imports/regionhandler.py"
click node_economy "https://github.com/devzero32/factionmapv4/blob/main/Imports/economyHandler.py"
click node_turns "https://github.com/devzero32/factionmapv4/blob/main/Imports/turnshandler.py"
click node_battles "https://github.com/devzero32/factionmapv4/blob/main/Imports/mediatorhandler.py"
click node_models "https://github.com/devzero32/factionmapv4/blob/main/Imports/classhandler.py"
click node_json "https://github.com/devzero32/factionmapv4/blob/main/Imports/jsonhandler.py"
click node_factiondata "https://github.com/devzero32/factionmapv4/blob/main/Data/factions.json"
click node_regiondata "https://github.com/devzero32/factionmapv4/blob/main/Data/regions.json"
click node_turnstate "https://github.com/devzero32/factionmapv4/blob/main/Data/turns.json"
click node_battledata "https://github.com/devzero32/factionmapv4/blob/main/Data/mediator.json"
click node_tradedata "https://github.com/devzero32/factionmapv4/blob/main/Data/trades.json"
click node_map "https://github.com/devzero32/factionmapv4/blob/main/Imports/imagehandler.py"
click node_images "https://github.com/devzero32/factionmapv4/tree/main/Data/Map"
click node_logos "https://github.com/devzero32/factionmapv4/tree/main/Data/Logos"
click node_embeds "https://github.com/devzero32/factionmapv4/blob/main/Imports/embedhandler.py"
click node_admin "https://github.com/devzero32/factionmapv4/blob/main/Imports/adminhandler.py"

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_bot,node_admin toneBlue
class node_factions,node_armies,node_regions,node_economy,node_turns,node_battles,node_models toneAmber
class node_json,node_factiondata,node_regiondata,node_turnstate,node_battledata,node_tradedata toneMint
class node_map,node_images,node_logos,node_embeds toneRose
class node_players,node_discord toneIndigo
```

## Components

### Discord interface

- [Command bot](https://github.com/devzero32/factionmapv4/blob/main/main.py): `main.py`
- [Admin and logs](https://github.com/devzero32/factionmapv4/blob/main/Imports/adminhandler.py): `Imports/adminhandler.py`

### Game systems

- [Faction management](https://github.com/devzero32/factionmapv4/blob/main/Imports/factionshandler.py): `Imports/factionshandler.py`
- [Army operations](https://github.com/devzero32/factionmapv4/blob/main/Imports/armyhandler.py): `Imports/armyhandler.py`
- [Region operations](https://github.com/devzero32/factionmapv4/blob/main/Imports/regionhandler.py): `Imports/regionhandler.py`
- [Trade economy](https://github.com/devzero32/factionmapv4/blob/main/Imports/economyHandler.py): `Imports/economyHandler.py`
- [Turn scheduler](https://github.com/devzero32/factionmapv4/blob/main/Imports/turnshandler.py): `Imports/turnshandler.py`
- [Battle mediation](https://github.com/devzero32/factionmapv4/blob/main/Imports/mediatorhandler.py): `Imports/mediatorhandler.py`
- [Game models](https://github.com/devzero32/factionmapv4/blob/main/Imports/classhandler.py): `Imports/classhandler.py`

### Game state

- [JSON access](https://github.com/devzero32/factionmapv4/blob/main/Imports/jsonhandler.py): `Imports/jsonhandler.py`
- [Faction records](https://github.com/devzero32/factionmapv4/blob/main/Data/factions.json): `Data/factions.json`
- [Region records](https://github.com/devzero32/factionmapv4/blob/main/Data/regions.json): `Data/regions.json`
- [Turn records](https://github.com/devzero32/factionmapv4/blob/main/Data/turns.json): `Data/turns.json`
- [Battle records](https://github.com/devzero32/factionmapv4/blob/main/Data/mediator.json): `Data/mediator.json`
- [Trade records](https://github.com/devzero32/factionmapv4/blob/main/Data/trades.json): `Data/trades.json`

### Presentation

- [Map rendering](https://github.com/devzero32/factionmapv4/blob/main/Imports/imagehandler.py): `Imports/imagehandler.py`
- [Map assets](https://github.com/devzero32/factionmapv4/tree/main/Data/Map): `Data/Map`
- [Faction logos](https://github.com/devzero32/factionmapv4/tree/main/Data/Logos): `Data/Logos`
- [Response embeds](https://github.com/devzero32/factionmapv4/blob/main/Imports/embedhandler.py): `Imports/embedhandler.py`

### Other components

- **Faction players**
- **Discord platform**

## Connections

- Faction players → Discord platform: issue commands
- Discord platform → Command bot: deliver interactions
- Command bot → Discord platform: send responses
- Command bot → Faction management: dispatch setup
- Command bot → Army operations: dispatch army actions
- Command bot → Region operations: dispatch region actions
- Command bot → Turn scheduler: start turn sequence
- Command bot → Battle mediation: dispatch battle actions
- Command bot → Admin and logs: log commands
- Faction management → JSON access: read and update
- Army operations → JSON access: read and update
- Region operations → JSON access: read and update
- Trade economy → JSON access: read and update
- Turn scheduler → JSON access: read and update
- Battle mediation → JSON access: read battle state
- Game models → JSON access: load game data
- JSON access → Faction records: read and write
- JSON access → Region records: read and write
- JSON access → Turn records: read and write
- Battle mediation → Battle records: read and write
- Trade economy → Trade records: manage trades
- Turn scheduler → Trade economy: distribute trades
- Region operations → Map rendering: update borders and buildings
- Map rendering → Map assets: load map assets
- Faction management → Faction logos: save and use logos
- Map rendering → Command bot: provide map output
- Faction management → Response embeds: format responses
- Army operations → Response embeds: format responses
- Region operations → Response embeds: format responses
- Admin and logs → Discord platform: check roles