# vitthalhumbe/fishpond architecture

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

- Interactive diagram: https://gitdiagram.com/vitthalhumbe/fishpond
- Repository: https://github.com/vitthalhumbe/fishpond

## Overview

1. **What this repository is**
   - A single-process Python simulation of an ecosystem.
   - It combines a real-time Pygame visual simulation with a genetic algorithm that evolves fish traits over generations.

2. **Execution boundary**
   - The project is run from `algorithm/main.py`.
   - That file is the top-level orchestrator: it starts the simulation loop, updates agents each frame, and triggers any result graphing/visualization.

3. **Core runtime loop**
   - The simulation is stateful and frame-driven.
   - Each tick updates fish movement, shark pursuit, collisions/encounters, survival status, and generation progression.
   - The loop is also responsible for rendering the current world state in Pygame.

4. **Agent model: `algorithm/agents.py`**
   - This is the behavioral layer for the two entity types: fish and shark.
   - Fish implement flocking-style motion: alignment, separation, and cohesion, plus individual traits that affect survival.
   - The shark acts as a predator with a vision cone / detection logic and chase behavior when fish enter range.

5. **Evolution engine: `algorithm/genetic_algorithm.py`**
   - This module handles the generational boundary between simulations.
   - It selects surviving fish, applies crossover and mutation, and produces the next population.
   - The evolved output is a new set of fish traits, not a new architecture level; the simulation remains the same, but the population parameters change.

6. **Configuration boundary: `algorithm/variables.py`**
   - Central place for tunable constants such as screen size, population count, speeds, vision ranges, and likely mutation/evolution settings.
   - This module acts as the shared config source for both the simulation and the genetic algorithm.

7. **Visualization and metrics**
   - `algorithm/graphs.py` appears to provide result plotting or analysis of simulation outcomes across generations.
   - The README also mentions “graphing,” so the architecture likely includes a post-run or side-panel visualization path for performance over time.

8. **Data flow between modules**
   - `variables.py` defines the constants used by both agent behavior and evolutionary rules.
   - `agents.py` produces the per-frame state updates and survival outcomes.
   - `genetic_algorithm.py` consumes those outcomes at the end of a generation and returns a new population.
   - `main.py` coordinates this loop and passes data to rendering/graphs.

9. **Important domain boundaries**
   - **Simulation boundary:** the real-time world of fish and shark in Pygame.
   - **Evolution boundary:** generation transitions where traits are copied, crossed, and mutated.
   - **Analysis boundary:** graphing/reporting of results, separate from the live agent behavior.

10. **External dependencies that matter**
   - **Pygame** is the rendering/input/timing layer and defines the interactive simulation runtime.
   - **NumPy** is likely used for vector math and population/fitness calculations.
   - There is no indication of a backend server, database, or network dependency.

11. **Project structure implications**
   - This is not a multi-service app; it is a compact simulation program with a clear split between orchestration, agent behavior, evolutionary logic, and configuration.
   - For an architecture diagram, the main boxes should be: `main.py` at center, `agents.py` and `genetic_algorithm.py` as the two logic subsystems, `variables.py` as shared config, and `graphs.py` as the reporting/analysis path.

12. **How to think about the system**
   - The fish population is the evolving asset.
   - The shark is the environmental pressure.
   - Survival time is the implicit fitness signal that feeds the genetic algorithm.
   - The simulation repeats until a generation ends, then the next population is synthesized and the cycle continues.

Main entry points: [`algorithm/main.py`](https://github.com/vitthalhumbe/fishpond/blob/main/algorithm/main.py) (Main loop), [`algorithm/variables.py`](https://github.com/vitthalhumbe/fishpond/blob/main/algorithm/variables.py) (Variables), [`algorithm/genetic_algorithm.py`](https://github.com/vitthalhumbe/fishpond/blob/main/algorithm/genetic_algorithm.py) (Select), [`algorithm/agents.py`](https://github.com/vitthalhumbe/fishpond/blob/main/algorithm/agents.py) (Fish)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime"]
  node_main["Main loop<br/>orchestrator<br/>[main.py]"]
  node_fish(("Fish<br/>agent<br/>[agents.py]"))
  node_shark(("Shark<br/>predator<br/>[agents.py]"))
end

subgraph group_evolution["Evolution"]
  node_selection["Select<br/>fitness"]
  node_breed["Crossover<br/>recombine"]
  node_mutate["Mutate<br/>variation"]
end

subgraph group_analysis["Analysis"]
  node_graphs["Graphs<br/>reporting<br/>[graphs.py]"]
end

subgraph group_shared["Shared"]
  node_config["Variables<br/>config<br/>[variables.py]"]
end

subgraph group_external["External"]
  node_pygame["Pygame<br/>rendering lib"]
  node_numpy["NumPy<br/>math lib"]
end

node_main -->|"updates"| node_fish
node_main -->|"updates"| node_shark
node_main -->|"ends gen"| node_selection
node_selection -->|"parents"| node_breed
node_breed -->|"offspring"| node_mutate
node_mutate -->|"next pop"| node_fish
node_main -->|"reports"| node_graphs
node_config -->|"tunes"| node_main
node_config -->|"tunes"| node_fish
node_config -->|"tunes"| node_shark
node_config -->|"tunes"| node_selection
node_main -->|"renders"| node_pygame
node_fish -->|"vectors"| node_numpy
node_selection -->|"fitness"| node_numpy

click node_main "https://github.com/vitthalhumbe/fishpond/blob/main/algorithm/main.py"
click node_fish "https://github.com/vitthalhumbe/fishpond/blob/main/algorithm/agents.py"
click node_shark "https://github.com/vitthalhumbe/fishpond/blob/main/algorithm/agents.py"
click node_selection "https://github.com/vitthalhumbe/fishpond/blob/main/algorithm/genetic_algorithm.py"
click node_breed "https://github.com/vitthalhumbe/fishpond/blob/main/algorithm/genetic_algorithm.py"
click node_mutate "https://github.com/vitthalhumbe/fishpond/blob/main/algorithm/genetic_algorithm.py"
click node_graphs "https://github.com/vitthalhumbe/fishpond/blob/main/algorithm/graphs.py"
click node_config "https://github.com/vitthalhumbe/fishpond/blob/main/algorithm/variables.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_main,node_fish,node_shark toneBlue
class node_selection,node_breed,node_mutate toneAmber
class node_graphs toneMint
class node_config toneRose
class node_pygame,node_numpy toneIndigo
```

## Components

### Runtime

Live simulation and agent behavior.

- [Main loop](https://github.com/vitthalhumbe/fishpond/blob/main/algorithm/main.py): orchestrator · Top-level entrypoint that runs the frame loop, coordinates updates, and triggers generation changes and visualization. · `algorithm/main.py`
- [Fish](https://github.com/vitthalhumbe/fishpond/blob/main/algorithm/agents.py): agent · Evolving prey agents with flocking behavior and trait-driven survival. · `algorithm/agents.py`
- [Shark](https://github.com/vitthalhumbe/fishpond/blob/main/algorithm/agents.py): predator · Predator agent with detection and chase behavior that pressures fish survival. · `algorithm/agents.py`

### Evolution

Generation boundary and trait regeneration.

- [Select](https://github.com/vitthalhumbe/fishpond/blob/main/algorithm/genetic_algorithm.py): fitness · Chooses surviving fish that seed the next generation. · `algorithm/genetic_algorithm.py`
- [Crossover](https://github.com/vitthalhumbe/fishpond/blob/main/algorithm/genetic_algorithm.py): recombine · Combines parent traits to produce offspring candidates. · `algorithm/genetic_algorithm.py`
- [Mutate](https://github.com/vitthalhumbe/fishpond/blob/main/algorithm/genetic_algorithm.py): variation · Applies random trait changes to preserve diversity across generations. · `algorithm/genetic_algorithm.py`

### Analysis

Outcome plotting and reporting.

- [Graphs](https://github.com/vitthalhumbe/fishpond/blob/main/algorithm/graphs.py): reporting · Plots or summarizes simulation outcomes across generations. · `algorithm/graphs.py`

### Shared

Central configuration used across subsystems.

- [Variables](https://github.com/vitthalhumbe/fishpond/blob/main/algorithm/variables.py): config · Shared simulation constants for world size, populations, speeds, ranges, and mutation settings. · `algorithm/variables.py`

### External

Runtime dependencies outside the repository.

- **Pygame**: rendering lib · External rendering, timing, and interaction runtime for the live simulation.
- **NumPy**: math lib · External numerical library for vector and population calculations.

## Connections

- Main loop → Fish: updates · Runs per-frame fish behavior and state updates.
- Main loop → Shark: updates · Advances predator movement and pursuit each tick.
- Main loop → Select: ends gen · Hands off survival outcomes when a generation completes.
- Select → Crossover: parents · Uses survivors as inputs for offspring creation.
- Crossover → Mutate: offspring · Mutated children become the next candidate population.
- Mutate → Fish: next pop · Produces the next generation of fish traits.
- Main loop → Graphs: reports · Sends generation results for plotting or analysis.
- Variables → Main loop: tunes · Provides shared runtime constants.
- Variables → Fish: tunes · Feeds flocking, movement, and vision parameters.
- Variables → Shark: tunes · Feeds predator speed and detection parameters.
- Variables → Select: tunes · Defines population and evolution settings.
- Main loop → Pygame: renders · Uses Pygame for the visual simulation loop.
- Fish → NumPy: vectors · Relies on numerical/vector operations for movement and fitness math.
- Select → NumPy: fitness · Uses numerical routines for population scoring and selection.