# kevin-ding-dev/cyberfly architecture

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

- Interactive diagram: https://gitdiagram.com/kevin-ding-dev/cyberfly
- Repository: https://github.com/kevin-ding-dev/cyberfly

## Overview

Cyberfly is a MuJoCo/FlyGym functional simulation for walking, sugar foraging, and maze navigation, with PPO learning and recording/evaluation workflows. The principal workflow is a user command that configures a task, runs a physical environment using a sensory or learned controller, and produces task metrics or recordings; training commands additionally evaluate and persist policies. Maze navigation adds generated layouts, odor and wall sensing, exploration memory, and dopamine-like reward signals. Edges follow shown imports, calls, or README-documented behavior; unsampled subsystem internals are represented by their exact source paths, without inferring extra call chains.

Main entry points: [`cyberfly/maze_env.py`](https://github.com/kevin-ding-dev/cyberfly/blob/main/cyberfly/maze_env.py) (Maze environment), [`cyberfly/foraging.py`](https://github.com/kevin-ding-dev/cyberfly/blob/main/cyberfly/foraging.py) (Foraging environment), [`cyberfly/forage_cli.py`](https://github.com/kevin-ding-dev/cyberfly/blob/main/cyberfly/forage_cli.py) (Forage commands), [`cyberfly/maze_learning.py`](https://github.com/kevin-ding-dev/cyberfly/blob/main/cyberfly/maze_learning.py) (Maze PPO training)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Command workflows"]
  node_commands["Command dispatcher<br/>[__main__.py]"]
  node_forage_cli["Forage commands<br/>[forage_cli.py]"]
  node_maze_cli["Maze commands<br/>[maze_cli.py]"]
end

subgraph group_simulation["Simulation and sensing"]
  node_walk_env["Walking environment<br/>[env.py]"]
  node_sensory_brain["Sensory controller<br/>[brain.py]"]
  node_foraging_env["Foraging environment<br/>[foraging.py]"]
  node_config_validation["Config validation"]
  node_forage_checks["Foraging checks<br/>[forage_checks.py]"]
end

subgraph group_forage["Foraging learning"]
  node_forage_learning["Champion challenger<br/>[forage_learning.py]"]
  node_forage_outputs["Forage recording<br/>[forage_cli.py]"]
end

subgraph group_maze["Maze navigation"]
  node_maze_model["Maze layouts<br/>[maze.py]"]
  node_maze_controller["Maze brain<br/>[maze_brain.py]"]
  node_maze_env["Maze environment<br/>[maze_env.py]"]
  node_maze_learning["Maze PPO training<br/>[maze_learning.py]"]
  node_maze_checks["Maze checks<br/>[maze_checks.py]"]
end

subgraph group_shared["Shared learning"]
  node_ppo_learning["PPO training and evaluation<br/>[learning.py]"]
  node_training_device["Device selection<br/>[training_device.py]"]
end

node_user(("Researcher"))
node_physics["MuJoCo and FlyGym"]

node_user -->|"runs command"| node_commands
node_commands -->|"dispatches forage"| node_forage_cli
node_commands -->|"dispatches maze"| node_maze_cli
node_forage_cli -->|"runs episodes"| node_foraging_env
node_forage_cli -->|"starts training"| node_forage_learning
node_forage_cli -->|"records results"| node_forage_outputs
node_foraging_env -->|"extends"| node_walk_env
node_foraging_env -->|"uses controller"| node_sensory_brain
node_foraging_env -->|"validates config"| node_config_validation
node_walk_env -->|"simulates with"| node_physics
node_forage_cli -->|"runs checks"| node_forage_checks
node_forage_learning -->|"trains and evaluates"| node_foraging_env
node_forage_learning -->|"uses PPO"| node_ppo_learning
node_forage_learning -->|"uses encoder"| node_sensory_brain
node_maze_cli -->|"starts training"| node_maze_learning
node_maze_cli -->|"runs maze"| node_maze_env
node_maze_cli -->|"runs checks"| node_maze_checks
node_maze_env -->|"extends"| node_foraging_env
node_maze_env -->|"uses layout"| node_maze_model
node_maze_env -->|"uses navigation"| node_maze_controller
node_maze_env -->|"simulates with"| node_physics
node_maze_learning -->|"trains and evaluates"| node_maze_env
node_maze_learning -->|"uses encoder"| node_maze_controller
node_maze_learning -->|"uses PPO"| node_ppo_learning
node_maze_learning -->|"selects device"| node_training_device
node_maze_checks -->|"checks behavior"| node_maze_env

click node_commands "https://github.com/kevin-ding-dev/cyberfly/blob/main/cyberfly/__main__.py"
click node_forage_cli "https://github.com/kevin-ding-dev/cyberfly/blob/main/cyberfly/forage_cli.py"
click node_maze_cli "https://github.com/kevin-ding-dev/cyberfly/blob/main/cyberfly/maze_cli.py"
click node_walk_env "https://github.com/kevin-ding-dev/cyberfly/blob/main/cyberfly/env.py"
click node_sensory_brain "https://github.com/kevin-ding-dev/cyberfly/blob/main/cyberfly/brain.py"
click node_foraging_env "https://github.com/kevin-ding-dev/cyberfly/blob/main/cyberfly/foraging.py"
click node_config_validation "https://github.com/kevin-ding-dev/cyberfly/blob/main/cyberfly/config_validation.py"
click node_forage_checks "https://github.com/kevin-ding-dev/cyberfly/blob/main/cyberfly/forage_checks.py"
click node_forage_learning "https://github.com/kevin-ding-dev/cyberfly/blob/main/cyberfly/forage_learning.py"
click node_forage_outputs "https://github.com/kevin-ding-dev/cyberfly/blob/main/cyberfly/forage_cli.py"
click node_maze_model "https://github.com/kevin-ding-dev/cyberfly/blob/main/cyberfly/maze.py"
click node_maze_controller "https://github.com/kevin-ding-dev/cyberfly/blob/main/cyberfly/maze_brain.py"
click node_maze_env "https://github.com/kevin-ding-dev/cyberfly/blob/main/cyberfly/maze_env.py"
click node_maze_learning "https://github.com/kevin-ding-dev/cyberfly/blob/main/cyberfly/maze_learning.py"
click node_maze_checks "https://github.com/kevin-ding-dev/cyberfly/blob/main/cyberfly/maze_checks.py"
click node_ppo_learning "https://github.com/kevin-ding-dev/cyberfly/blob/main/cyberfly/learning.py"
click node_training_device "https://github.com/kevin-ding-dev/cyberfly/blob/main/cyberfly/training_device.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_commands,node_forage_cli,node_maze_cli toneBlue
class node_walk_env,node_sensory_brain,node_foraging_env,node_config_validation,node_forage_checks toneAmber
class node_forage_learning,node_forage_outputs toneMint
class node_maze_model,node_maze_controller,node_maze_env,node_maze_learning,node_maze_checks toneRose
class node_ppo_learning,node_training_device,node_user,node_physics toneIndigo
```

## Components

### Command workflows

- [Command dispatcher](https://github.com/kevin-ding-dev/cyberfly/blob/main/cyberfly/__main__.py): `cyberfly/__main__.py`
- [Forage commands](https://github.com/kevin-ding-dev/cyberfly/blob/main/cyberfly/forage_cli.py): `cyberfly/forage_cli.py`
- [Maze commands](https://github.com/kevin-ding-dev/cyberfly/blob/main/cyberfly/maze_cli.py): `cyberfly/maze_cli.py`

### Simulation and sensing

- [Walking environment](https://github.com/kevin-ding-dev/cyberfly/blob/main/cyberfly/env.py): `cyberfly/env.py`
- [Sensory controller](https://github.com/kevin-ding-dev/cyberfly/blob/main/cyberfly/brain.py): `cyberfly/brain.py`
- [Foraging environment](https://github.com/kevin-ding-dev/cyberfly/blob/main/cyberfly/foraging.py): `cyberfly/foraging.py`
- [Config validation](https://github.com/kevin-ding-dev/cyberfly/blob/main/cyberfly/config_validation.py): `cyberfly/config_validation.py`
- [Foraging checks](https://github.com/kevin-ding-dev/cyberfly/blob/main/cyberfly/forage_checks.py): `cyberfly/forage_checks.py`

### Foraging learning

- [Champion challenger](https://github.com/kevin-ding-dev/cyberfly/blob/main/cyberfly/forage_learning.py): `cyberfly/forage_learning.py`
- [Forage recording](https://github.com/kevin-ding-dev/cyberfly/blob/main/cyberfly/forage_cli.py): `cyberfly/forage_cli.py`

### Maze navigation

- [Maze layouts](https://github.com/kevin-ding-dev/cyberfly/blob/main/cyberfly/maze.py): `cyberfly/maze.py`
- [Maze brain](https://github.com/kevin-ding-dev/cyberfly/blob/main/cyberfly/maze_brain.py): `cyberfly/maze_brain.py`
- [Maze environment](https://github.com/kevin-ding-dev/cyberfly/blob/main/cyberfly/maze_env.py): `cyberfly/maze_env.py`
- [Maze PPO training](https://github.com/kevin-ding-dev/cyberfly/blob/main/cyberfly/maze_learning.py): `cyberfly/maze_learning.py`
- [Maze checks](https://github.com/kevin-ding-dev/cyberfly/blob/main/cyberfly/maze_checks.py): `cyberfly/maze_checks.py`

### Shared learning

- [PPO training and evaluation](https://github.com/kevin-ding-dev/cyberfly/blob/main/cyberfly/learning.py): `cyberfly/learning.py`
- [Device selection](https://github.com/kevin-ding-dev/cyberfly/blob/main/cyberfly/training_device.py): `cyberfly/training_device.py`

### Other components

- **Researcher**
- **MuJoCo and FlyGym**

## Connections

- Researcher → Command dispatcher: runs command (evidence: `README.md`)
- Command dispatcher → Forage commands: dispatches forage (evidence: `cyberfly/__main__.py`)
- Command dispatcher → Maze commands: dispatches maze (evidence: `cyberfly/__main__.py`)
- Forage commands → Foraging environment: runs episodes (evidence: `cyberfly/forage_cli.py`)
- Forage commands → Champion challenger: starts training (evidence: `cyberfly/forage_cli.py`)
- Forage commands → Forage recording: records results (evidence: `README.md`)
- Foraging environment → Walking environment: extends (evidence: `cyberfly/foraging.py`)
- Foraging environment → Sensory controller: uses controller (evidence: `cyberfly/foraging.py`)
- Foraging environment → Config validation: validates config (evidence: `cyberfly/foraging.py`)
- Walking environment → MuJoCo and FlyGym: simulates with (evidence: `README.md`)
- Forage commands → Foraging checks: runs checks (evidence: `README.md`)
- Champion challenger → Foraging environment: trains and evaluates (evidence: `cyberfly/forage_learning.py`)
- Champion challenger → PPO training and evaluation: uses PPO (evidence: `cyberfly/forage_learning.py`)
- Champion challenger → Sensory controller: uses encoder (evidence: `cyberfly/forage_learning.py`)
- Maze commands → Maze PPO training: starts training (evidence: `cyberfly/maze_cli.py`)
- Maze commands → Maze environment: runs maze (evidence: `cyberfly/maze_cli.py`)
- Maze commands → Maze checks: runs checks (evidence: `cyberfly/maze_cli.py`)
- Maze environment → Foraging environment: extends (evidence: `cyberfly/maze_env.py`)
- Maze environment → Maze layouts: uses layout (evidence: `cyberfly/maze_env.py`)
- Maze environment → Maze brain: uses navigation (evidence: `cyberfly/maze_env.py`)
- Maze environment → MuJoCo and FlyGym: simulates with (evidence: `README.md`)
- Maze PPO training → Maze environment: trains and evaluates (evidence: `cyberfly/maze_learning.py`)
- Maze PPO training → Maze brain: uses encoder (evidence: `cyberfly/maze_learning.py`)
- Maze PPO training → PPO training and evaluation: uses PPO (evidence: `cyberfly/maze_learning.py`)
- Maze PPO training → Device selection: selects device (evidence: `cyberfly/maze_learning.py`)
- Maze checks → Maze environment: checks behavior (evidence: `cyberfly/maze_checks.py`)
