# planet-source-code/roberto-aguirre-maturana-ant-farm-simulator__1-67102 architecture

> Architecture diagram of the GitHub repository planet-source-code/roberto-aguirre-maturana-ant-farm-simulator__1-67102, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-04-06). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/planet-source-code/roberto-aguirre-maturana-ant-farm-simulator__1-67102
- Repository: https://github.com/planet-source-code/roberto-aguirre-maturana-ant-farm-simulator__1-67102

## Overview

1. **Project type and runtime**
   - This is a **Visual Basic 6 desktop application**. The repository is a classic VB6 project (`Ant Farm Simulator.vbp`) built around forms, with no separate library, service, or web backend.

2. **Primary purpose**
   - The app simulates **ant colony foraging behavior** using local environment signals (“odor traces”) rather than memory. The core idea is a **single-process simulation loop** that animates ants searching for food and returning it to the nest.

3. **Main application boundary**
   - The main boundary is the **simulation window** in `frmAntsSimulator.frm`. This is the central UI and likely contains most of the application logic, rendering, and update cycle.

4. **Simulation model**
   - The simulation uses a small set of interacting entities:
     - **Ants**
     - **Nest**
     - **Food sources**
     - **Odor traces** on the ground
   - Two trace types matter: **nest traces** and **food traces**, each with different direction-following behavior.

5. **Behavioral flow**
   - Ants operate in three practical states:
     - **Explorer**: leaves the nest and moves randomly while emitting a nest trace.
     - **Tracker**: when not carrying food, follows food traces toward stronger scent.
     - **Deliverer**: when carrying food, follows food traces and then nest traces in the opposite gradient direction to return home.
   - This state-based behavior is the heart of the architecture.

6. **Environment update loop**
   - The simulation likely runs as a repeated **time-step / tick loop** inside the main form. Each cycle would:
     - Move ants
     - Detect food/nest/traces
     - Increase trace intensity when reinforced
     - Fade traces over time
     - Repaint the scene

7. **Rendering and visualization**
   - Visual output is probably handled directly by the main form’s drawing surface, rather than by a separate rendering engine. The screenshot in the README suggests the app visually overlays:
     - Ant positions
     - Brown nest scent trails
     - Green food scent trails
     - Food and nest locations

8. **Configuration boundary**
   - `options.frm` is the configuration surface. It likely controls simulation parameters such as number of ants, trace persistence, movement behavior, or speeds. This is the main user-facing input boundary besides starting/stopping the simulation.

9. **Auxiliary UI forms**
   - `frmSplash.frm` is a startup splash screen, and `frmAbout.frm` is the standard about dialog. These are supporting UI components only; they do not appear to participate in simulation logic.

10. **Data storage and persistence**
   - There is no evidence of a database, file-based model, or network dependency. The app appears to be **fully in-memory**, with state reset when the program closes. The `.frx` files are VB6 form resource companions, not application data stores.

11. **Likely architectural shape**
   - The repository is best understood as a **form-driven monolith**:
     - UI and simulation logic are tightly coupled in the main form
     - Supporting forms handle startup/about/options
     - No visible layered architecture or service separation

12. **What to draw in an architecture diagram**
   - Show a single desktop executable with:
     - **Main simulation form** at the center
     - **Options dialog** feeding parameters into the simulation
     - **Splash/about dialogs** as auxiliary UI
     - **In-memory simulation state** consisting of ants, traces, food, and nest
     - A closed loop between **simulation update** and **screen rendering**

Main entry points: [`frmAntsSimulator.frm`](https://github.com/planet-source-code/roberto-aguirre-maturana-ant-farm-simulator__1-67102/blob/master/frmAntsSimulator.frm) (Tick loop), [`Ant Farm Simulator.vbp`](https://github.com/planet-source-code/roberto-aguirre-maturana-ant-farm-simulator__1-67102/blob/HEAD/Ant%20Farm%20Simulator.vbp) (VB6 project), [`options.frm`](https://github.com/planet-source-code/roberto-aguirre-maturana-ant-farm-simulator__1-67102/blob/master/options.frm) (Options), [`frmSplash.frm`](https://github.com/planet-source-code/roberto-aguirre-maturana-ant-farm-simulator__1-67102/blob/master/frmSplash.frm) (Splash)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["UI shell"]
  node_vbp["VB6 project<br/>desktop app"]
  node_main["Simulation<br/>main form"]
  node_options["Options<br/>settings form<br/>[options.frm]"]
  node_splash["Splash<br/>startup form<br/>[frmSplash.frm]"]
  node_about["About<br/>dialog form<br/>[frmAbout.frm]"]
end

subgraph group_sim["Simulation core"]
  node_loop(("Tick loop<br/>update cycle"))
  node_render(("Render<br/>drawing"))
  node_behavior{{"Behavior<br/>state machine"}}
end

subgraph group_model["World state"]
  node_ants(("Ants<br/>agents"))
  node_traces["Odor traces<br/>signals"]
  node_nest[("Nest<br/>home base")]
  node_food[("Food sources<br/>resource nodes")]
  node_params["Parameters<br/>settings data"]
end

node_vbp -->|"launches"| node_splash
node_vbp -->|"opens"| node_main
node_vbp -.->|"includes"| node_about
node_vbp -.->|"includes"| node_options
node_splash -->|"continues to"| node_main
node_options -->|"edits"| node_params
node_main -->|"reads"| node_params
node_main -->|"drives"| node_loop
node_loop -->|"updates"| node_behavior
node_loop -->|"moves"| node_ants
node_loop -->|"reinforces"| node_traces
node_loop -->|"checks"| node_food
node_loop -->|"checks"| node_nest
node_behavior -->|"follows"| node_traces
node_behavior -->|"returns to"| node_nest
node_behavior -->|"seeks"| node_food
node_main -->|"paints"| node_render
node_render -->|"draws"| node_ants
node_render -->|"draws"| node_traces
node_render -->|"draws"| node_nest
node_render -->|"draws"| node_food

click node_vbp "https://github.com/planet-source-code/roberto-aguirre-maturana-ant-farm-simulator__1-67102/blob/master/Ant Farm Simulator.vbp"
click node_main "https://github.com/planet-source-code/roberto-aguirre-maturana-ant-farm-simulator__1-67102/blob/master/frmAntsSimulator.frm"
click node_options "https://github.com/planet-source-code/roberto-aguirre-maturana-ant-farm-simulator__1-67102/blob/master/options.frm"
click node_splash "https://github.com/planet-source-code/roberto-aguirre-maturana-ant-farm-simulator__1-67102/blob/master/frmSplash.frm"
click node_about "https://github.com/planet-source-code/roberto-aguirre-maturana-ant-farm-simulator__1-67102/blob/master/frmAbout.frm"
click node_loop "https://github.com/planet-source-code/roberto-aguirre-maturana-ant-farm-simulator__1-67102/blob/master/frmAntsSimulator.frm"
click node_render "https://github.com/planet-source-code/roberto-aguirre-maturana-ant-farm-simulator__1-67102/blob/master/frmAntsSimulator.frm"
click node_behavior "https://github.com/planet-source-code/roberto-aguirre-maturana-ant-farm-simulator__1-67102/blob/master/frmAntsSimulator.frm"

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_vbp,node_main,node_options,node_splash,node_about toneBlue
class node_loop,node_render,node_behavior toneAmber
class node_ants,node_traces,node_nest,node_food,node_params toneMint
```

## Components

### UI shell

Forms that start, configure, and display the simulator

- [VB6 project](https://github.com/planet-source-code/roberto-aguirre-maturana-ant-farm-simulator__1-67102/blob/HEAD/Ant%20Farm%20Simulator.vbp): desktop app · Classic VB6 executable project root · `Ant Farm Simulator.vbp`
- [Simulation](https://github.com/planet-source-code/roberto-aguirre-maturana-ant-farm-simulator__1-67102/blob/master/frmAntsSimulator.frm): main form · Central simulation window and primary application boundary · `frmAntsSimulator.frm`
- [Options](https://github.com/planet-source-code/roberto-aguirre-maturana-ant-farm-simulator__1-67102/blob/master/options.frm): settings form · User controls for simulation parameters · `options.frm`
- [Splash](https://github.com/planet-source-code/roberto-aguirre-maturana-ant-farm-simulator__1-67102/blob/master/frmSplash.frm): startup form · Launch splash screen · `frmSplash.frm`
- [About](https://github.com/planet-source-code/roberto-aguirre-maturana-ant-farm-simulator__1-67102/blob/master/frmAbout.frm): dialog form · Application information dialog · `frmAbout.frm`

### Simulation core

Main loop and behavior that drive the ant colony model

- [Tick loop](https://github.com/planet-source-code/roberto-aguirre-maturana-ant-farm-simulator__1-67102/blob/master/frmAntsSimulator.frm): update cycle · Repeated simulation step for movement, sensing, fading, and redraw · `frmAntsSimulator.frm`
- [Render](https://github.com/planet-source-code/roberto-aguirre-maturana-ant-farm-simulator__1-67102/blob/master/frmAntsSimulator.frm): drawing · Paints ants, nest, food, and odor trails onto the form · `frmAntsSimulator.frm`
- [Behavior](https://github.com/planet-source-code/roberto-aguirre-maturana-ant-farm-simulator__1-67102/blob/master/frmAntsSimulator.frm): state machine · Explorer, tracker, and deliverer behavior rules · `frmAntsSimulator.frm`

### World state

In-memory entities and signals used by the simulation

- **Ants**: agents · Moving agents that search for food and return it to the nest
- **Odor traces**: signals · Nest and food scent trails that guide movement
- **Nest**: home base · Colony origin and return target
- **Food sources**: resource nodes · Harvestable targets that ants discover and carry from
- **Parameters**: settings data · Simulation values such as counts, speeds, and trace persistence

## Connections

- VB6 project → Splash: launches · Project starts the splash screen before the simulator
- VB6 project → Simulation: opens · Primary executable window
- VB6 project → About: includes · Dialog is part of the desktop app
- VB6 project → Options: includes · Settings form is part of the desktop app
- Splash → Simulation: continues to · Startup flow transitions into the simulation window
- Options → Parameters: edits · User changes simulation settings
- Simulation → Parameters: reads · Main form consumes current simulation parameters
- Simulation → Tick loop: drives · Main form owns the repeated simulation tick
- Tick loop → Behavior: updates · Applies ant state transitions and movement rules
- Tick loop → Ants: moves · Advances ant positions and carrying state
- Tick loop → Odor traces: reinforces · Strengthens and fades odor trails over time
- Tick loop → Food sources: checks · Detects food pickup and depletion
- Tick loop → Nest: checks · Detects home return and delivery
- Behavior → Odor traces: follows · Tracker and deliverer behavior depends on scent gradients
- Behavior → Nest: returns to · Deliverer mode targets the nest
- Behavior → Food sources: seeks · Explorer/tracker behavior seeks food sources
- Simulation → Render: paints · Main form draws the current world state
- Render → Ants: draws · Visualizes ant positions
- Render → Odor traces: draws · Overlays brown and green scent trails
- Render → Nest: draws · Renders the nest location
- Render → Food sources: draws · Renders food locations
