# aamirsahil/antforagesim architecture

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

- Interactive diagram: https://gitdiagram.com/aamirsahil/antforagesim
- Repository: https://github.com/aamirsahil/antforagesim

## Overview

AntForageSim is a browser-based ant-foraging simulation. Users configure and run it through the page controls; the controller creates and advances a simulation, which updates the world, cells, and learning agents. The controller then refreshes the canvas and dashboard. The excerpts document these runtime calls and the agent’s Q-learning, but the README gives no further product description; unsampled files and wiring are not inferred.

Main entry points: [`index.js`](https://github.com/aamirsahil/antforagesim/blob/main/index.js) (Page controller), [`simulation.js`](https://github.com/aamirsahil/antforagesim/blob/main/simulation.js) (Simulation), [`world.js`](https://github.com/aamirsahil/antforagesim/blob/main/world.js) (World state), [`agent.js`](https://github.com/aamirsahil/antforagesim/blob/main/agent.js) (Ant agent)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_control["Controls and display"]
  node_controller["Page controller<br/>[index.js]"]
  node_canvas["World canvas<br/>[canvas.js]"]
  node_dashboard["Stats dashboard<br/>[dom.js]"]
end

subgraph group_simulation["Simulation runtime"]
  node_simulation["Simulation<br/>[simulation.js]"]
end

subgraph group_foraging["Foraging and learning"]
  node_agent["Ant agent<br/>[agent.js]"]
  node_qlearn["Q-learning<br/>[qlearn.js]"]
end

subgraph group_environment["World environment"]
  node_world["World state<br/>[world.js]"]
  node_cell["Grid cell<br/>[cell.js]"]
  node_map["Default map<br/>[map.js]"]
end

node_user(("User"))
node_plotly["Plotly charts"]

node_user -->|"operates controls"| node_controller
node_controller -->|"creates and updates"| node_simulation
node_simulation -->|"creates and updates"| node_world
node_simulation -->|"loads map"| node_map
node_world -->|"creates and updates"| node_cell
node_world -->|"updates agents"| node_agent
node_simulation -->|"creates agents"| node_agent
node_agent -->|"learns and selects"| node_qlearn
node_controller -->|"renders world"| node_canvas
node_controller -->|"updates stats"| node_dashboard
node_dashboard -->|"extends charts"| node_plotly

click node_controller "https://github.com/aamirsahil/antforagesim/blob/main/index.js"
click node_canvas "https://github.com/aamirsahil/antforagesim/blob/main/canvas.js"
click node_dashboard "https://github.com/aamirsahil/antforagesim/blob/main/dom.js"
click node_simulation "https://github.com/aamirsahil/antforagesim/blob/main/simulation.js"
click node_world "https://github.com/aamirsahil/antforagesim/blob/main/world.js"
click node_cell "https://github.com/aamirsahil/antforagesim/blob/main/cell.js"
click node_map "https://github.com/aamirsahil/antforagesim/blob/main/map.js"
click node_agent "https://github.com/aamirsahil/antforagesim/blob/main/agent.js"
click node_qlearn "https://github.com/aamirsahil/antforagesim/blob/main/qlearn.js"

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_controller,node_canvas,node_dashboard,node_user toneBlue
class node_simulation toneAmber
class node_agent,node_qlearn toneMint
class node_world,node_cell,node_map toneRose
class node_plotly toneIndigo
```

## Components

### Controls and display

- [Page controller](https://github.com/aamirsahil/antforagesim/blob/main/index.js): `index.js`
- [World canvas](https://github.com/aamirsahil/antforagesim/blob/main/canvas.js): `canvas.js`
- [Stats dashboard](https://github.com/aamirsahil/antforagesim/blob/main/dom.js): `dom.js`

### Simulation runtime

- [Simulation](https://github.com/aamirsahil/antforagesim/blob/main/simulation.js): `simulation.js`

### Foraging and learning

- [Ant agent](https://github.com/aamirsahil/antforagesim/blob/main/agent.js): `agent.js`
- [Q-learning](https://github.com/aamirsahil/antforagesim/blob/main/qlearn.js): `qlearn.js`

### World environment

- [World state](https://github.com/aamirsahil/antforagesim/blob/main/world.js): `world.js`
- [Grid cell](https://github.com/aamirsahil/antforagesim/blob/main/cell.js): `cell.js`
- [Default map](https://github.com/aamirsahil/antforagesim/blob/main/map.js): `map.js`

### Other components

- **User**
- **Plotly charts**

## Connections

- User → Page controller: operates controls (evidence: `index.js`)
- Page controller → Simulation: creates and updates (evidence: `index.js`)
- Simulation → World state: creates and updates (evidence: `simulation.js`)
- Simulation → Default map: loads map (evidence: `simulation.js`)
- World state → Grid cell: creates and updates (evidence: `world.js`)
- World state → Ant agent: updates agents (evidence: `world.js`)
- Simulation → Ant agent: creates agents (evidence: `simulation.js`)
- Ant agent → Q-learning: learns and selects (evidence: `agent.js`)
- Page controller → World canvas: renders world (evidence: `index.js`)
- Page controller → Stats dashboard: updates stats (evidence: `index.js`)
- Stats dashboard → Plotly charts: extends charts (evidence: `dom.js`)
