# remizzzzz/ia04 architecture

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

- Interactive diagram: https://gitdiagram.com/remizzzzz/ia04
- Repository: https://github.com/remizzzzz/ia04

## Overview

This repository implements a Go grid-combat simulation, currently driven by a terminal loop. The main workflow is CLI entry → simulation runner → world setup and turns → unit decisions → world movement and rendering. Units can act independently or coordinate through an Army; the world owns perception, pathfinding, and turn resolution. The README describes web/ebiten clients, headless experiments, richer unit roles, and S0–S3 strategies, but the sampled runtime does not establish those as implemented capabilities; shooting is recognized but has no effect. Edges below reflect only shown calls and documented relationships.

Main entry points: [`cmd/world/world.go`](https://github.com/remizzzzz/ia04/blob/master/cmd/world/world.go) (Turn controller), [`cmd/agents/unit.go`](https://github.com/remizzzzz/ia04/blob/master/cmd/agents/unit.go) (Unit agent), [`cmd/sim/simulation.go`](https://github.com/remizzzzz/ia04/blob/master/cmd/sim/simulation.go) (Simulation runner), [`cmd/agents/army.go`](https://github.com/remizzzzz/ia04/blob/master/cmd/agents/army.go) (Army strategy)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Simulation runtime"]
  node_entry["CLI entry<br/>[main.go]"]
  node_runner["Simulation runner<br/>[simulation.go]"]
  node_renderer["Terminal renderer<br/>[world.go]"]
end

subgraph group_agents["Agent coordination"]
  node_unit["Unit agent<br/>[unit.go]"]
  node_army["Army strategy<br/>[army.go]"]
end

subgraph group_world["World mechanics"]
  node_turn["Turn controller<br/>[world.go]"]
  node_grid["Grid and movement<br/>[world.go]"]
  node_perception["Vision and routing<br/>[world.go]"]
  node_geometry["Grid geometry<br/>[geometry.go]"]
  node_random["Random utilities<br/>[utils.go]"]
end

node_user(("User"))

node_user -->|"starts"| node_entry
node_entry -->|"runs simulation"| node_runner
node_runner -->|"creates world"| node_grid
node_runner -->|"runs turns"| node_turn
node_runner -->|"prints world"| node_renderer
node_turn -->|"sends orders"| node_unit
node_unit -->|"returns actions"| node_turn
node_turn -->|"updates awareness"| node_army
node_unit -->|"requests decision"| node_army
node_turn -->|"builds perception"| node_perception
node_turn -->|"applies movement"| node_grid
node_grid -->|"uses coordinates"| node_geometry
node_perception -->|"measures distance"| node_geometry
node_grid -->|"chooses free tiles"| node_random
node_army -->|"measures distance"| node_geometry
node_army -->|"checks membership"| node_random
node_unit -->|"uses positions"| node_geometry
node_unit -->|"chooses random moves"| node_random

click node_entry "https://github.com/remizzzzz/ia04/blob/master/cmd/main/main.go"
click node_runner "https://github.com/remizzzzz/ia04/blob/master/cmd/sim/simulation.go"
click node_renderer "https://github.com/remizzzzz/ia04/blob/master/cmd/world/world.go"
click node_unit "https://github.com/remizzzzz/ia04/blob/master/cmd/agents/unit.go"
click node_army "https://github.com/remizzzzz/ia04/blob/master/cmd/agents/army.go"
click node_turn "https://github.com/remizzzzz/ia04/blob/master/cmd/world/world.go"
click node_grid "https://github.com/remizzzzz/ia04/blob/master/cmd/world/world.go"
click node_perception "https://github.com/remizzzzz/ia04/blob/master/cmd/world/world.go"
click node_geometry "https://github.com/remizzzzz/ia04/blob/master/cmd/geometry/geometry.go"
click node_random "https://github.com/remizzzzz/ia04/blob/master/cmd/utils/utils.go"

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_entry,node_runner,node_renderer,node_user toneBlue
class node_unit,node_army toneAmber
class node_turn,node_grid,node_perception,node_geometry,node_random toneMint
```

## Components

### Simulation runtime

- [CLI entry](https://github.com/remizzzzz/ia04/blob/master/cmd/main/main.go): `cmd/main/main.go`
- [Simulation runner](https://github.com/remizzzzz/ia04/blob/master/cmd/sim/simulation.go): `cmd/sim/simulation.go`
- [Terminal renderer](https://github.com/remizzzzz/ia04/blob/master/cmd/world/world.go): `cmd/world/world.go`

### Agent coordination

- [Unit agent](https://github.com/remizzzzz/ia04/blob/master/cmd/agents/unit.go): `cmd/agents/unit.go`
- [Army strategy](https://github.com/remizzzzz/ia04/blob/master/cmd/agents/army.go): `cmd/agents/army.go`

### World mechanics

- [Turn controller](https://github.com/remizzzzz/ia04/blob/master/cmd/world/world.go): `cmd/world/world.go`
- [Grid and movement](https://github.com/remizzzzz/ia04/blob/master/cmd/world/world.go): `cmd/world/world.go`
- [Vision and routing](https://github.com/remizzzzz/ia04/blob/master/cmd/world/world.go): `cmd/world/world.go`
- [Grid geometry](https://github.com/remizzzzz/ia04/blob/master/cmd/geometry/geometry.go): `cmd/geometry/geometry.go`
- [Random utilities](https://github.com/remizzzzz/ia04/blob/master/cmd/utils/utils.go): `cmd/utils/utils.go`

### Other components

- **User**

## Connections

- User → CLI entry: starts
- CLI entry → Simulation runner: runs simulation (evidence: `cmd/main/main.go`)
- Simulation runner → Grid and movement: creates world (evidence: `cmd/sim/simulation.go`)
- Simulation runner → Turn controller: runs turns (evidence: `cmd/sim/simulation.go`)
- Simulation runner → Terminal renderer: prints world (evidence: `cmd/sim/simulation.go`)
- Turn controller → Unit agent: sends orders (evidence: `cmd/world/world.go`)
- Unit agent → Turn controller: returns actions (evidence: `cmd/world/world.go`)
- Turn controller → Army strategy: updates awareness (evidence: `cmd/world/world.go`)
- Unit agent → Army strategy: requests decision (evidence: `cmd/agents/unit.go`)
- Turn controller → Vision and routing: builds perception (evidence: `cmd/world/world.go`)
- Turn controller → Grid and movement: applies movement (evidence: `cmd/world/world.go`)
- Grid and movement → Grid geometry: uses coordinates (evidence: `cmd/world/world.go`)
- Vision and routing → Grid geometry: measures distance (evidence: `cmd/world/world.go`)
- Grid and movement → Random utilities: chooses free tiles (evidence: `cmd/world/world.go`)
- Army strategy → Grid geometry: measures distance (evidence: `cmd/agents/army.go`)
- Army strategy → Random utilities: checks membership (evidence: `cmd/agents/army.go`)
- Unit agent → Grid geometry: uses positions (evidence: `cmd/agents/unit.go`)
- Unit agent → Random utilities: chooses random moves (evidence: `cmd/agents/unit.go`)