# avbiswas/navigation-mappo-rl architecture

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

- Interactive diagram: https://gitdiagram.com/avbiswas/navigation-mappo-rl
- Repository: https://github.com/avbiswas/navigation-mappo-rl

## Overview

Multi Agent Navigation trains and evaluates cooperative agents in configurable obstacle courses. The main workflow is to choose a YAML scenario, train MAPPO against the multi-agent environment, save a model, then run inference in the original or another scenario. The environment supplies observations and rewards; its geometry, sensing, and rendering are distinct supporting stages. The README and source index establish the principal links, but several source excerpts are partial, so unsampled behavior is not expanded into additional flows.

Main entry points: [`nav/environment.py`](https://github.com/avbiswas/navigation-mappo-rl/blob/main/nav/environment.py) (Multi-agent environment), [`rl/mappo.py`](https://github.com/avbiswas/navigation-mappo-rl/blob/main/rl/mappo.py) (MAPPO trainer), [`train_mappo.py`](https://github.com/avbiswas/navigation-mappo-rl/blob/main/train_mappo.py) (Training entry point), [`inference.py`](https://github.com/avbiswas/navigation-mappo-rl/blob/main/inference.py) (Inference runner)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_scenario["Scenario and world"]
  node_scenarios["Scenario YAMLs"]
  node_schema["Environment schema<br/>[config_models.py]"]
end

subgraph group_simulation["Simulation and sensing"]
  node_environment["Multi-agent environment<br/>[environment.py]"]
  node_obstacles["Obstacles and boundary<br/>[obstacles.py]"]
  node_geometry["Geometry utilities<br/>[utils.py]"]
  node_lidar["Ray intersections"]
end

subgraph group_learning["MAPPO learning"]
  node_mappo["MAPPO trainer<br/>[mappo.py]"]
  node_encoder["Observation encoder"]
  node_distribution["Gaussian actions<br/>[distributions.py]"]
  node_rollouts["Rollout buffer"]
end

subgraph group_visualization["Rendering"]
  node_renderer_state["Render snapshot models<br/>[renderer_models.py]"]
  node_renderer["Live renderer<br/>[live_renderer.py]"]
end

subgraph group_execution["Train and evaluate"]
  node_trainer["Training entry point<br/>[train_mappo.py]"]
  node_inference["Inference runner<br/>[inference.py]"]
  node_saved_model["Saved model"]
end

node_user(("Experimenter"))

node_user -->|"selects"| node_scenarios
node_scenarios -->|"follows schema"| node_schema
node_user -->|"starts training"| node_trainer
node_trainer -->|"loads config"| node_scenarios
node_trainer -->|"trains in"| node_environment
node_trainer -->|"configures"| node_mappo
node_trainer -->|"configures"| node_encoder
node_environment -->|"uses config"| node_schema
node_environment -->|"uses geometry"| node_obstacles
node_environment -->|"uses utilities"| node_geometry
node_environment -->|"computes sensing"| node_lidar
node_environment -->|"creates snapshots"| node_renderer_state
node_environment -->|"updates display"| node_renderer
node_obstacles -->|"uses utilities"| node_geometry
node_lidar -->|"intersects shapes"| node_obstacles
node_lidar -->|"uses geometry types"| node_schema
node_renderer_state -->|"uses config types"| node_schema
node_renderer_state -->|"uses ray results"| node_lidar
node_renderer -->|"renders snapshots"| node_renderer_state
node_mappo -->|"encodes observations"| node_encoder
node_mappo -->|"uses action distribution"| node_distribution
node_mappo -->|"stores rollouts"| node_rollouts
node_mappo -->|"collects experience"| node_environment
node_mappo -->|"saves checkpoint"| node_saved_model
node_user -->|"starts evaluation"| node_inference
node_inference -->|"steps simulation"| node_environment
node_inference -->|"loads and predicts"| node_mappo
node_inference -->|"selects config"| node_scenarios
node_saved_model -->|"loads checkpoint"| node_inference

click node_scenarios "https://github.com/avbiswas/navigation-mappo-rl/tree/main/configs"
click node_schema "https://github.com/avbiswas/navigation-mappo-rl/blob/main/nav/config_models.py"
click node_environment "https://github.com/avbiswas/navigation-mappo-rl/blob/main/nav/environment.py"
click node_obstacles "https://github.com/avbiswas/navigation-mappo-rl/blob/main/nav/obstacles.py"
click node_geometry "https://github.com/avbiswas/navigation-mappo-rl/blob/main/nav/utils.py"
click node_lidar "https://github.com/avbiswas/navigation-mappo-rl/blob/main/nav/ray_intersection.py"
click node_renderer_state "https://github.com/avbiswas/navigation-mappo-rl/blob/main/nav/renderer_models.py"
click node_renderer "https://github.com/avbiswas/navigation-mappo-rl/blob/main/nav/live_renderer.py"
click node_trainer "https://github.com/avbiswas/navigation-mappo-rl/blob/main/train_mappo.py"
click node_mappo "https://github.com/avbiswas/navigation-mappo-rl/blob/main/rl/mappo.py"
click node_encoder "https://github.com/avbiswas/navigation-mappo-rl/blob/main/networks/actor_critic_network.py"
click node_distribution "https://github.com/avbiswas/navigation-mappo-rl/blob/main/rl/distributions.py"
click node_rollouts "https://github.com/avbiswas/navigation-mappo-rl/blob/main/rl/rollout_buffer_with_states.py"
click node_inference "https://github.com/avbiswas/navigation-mappo-rl/blob/main/inference.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_scenarios,node_schema toneBlue
class node_environment,node_obstacles,node_geometry,node_lidar toneAmber
class node_mappo,node_encoder,node_distribution,node_rollouts toneMint
class node_renderer_state,node_renderer toneRose
class node_trainer,node_inference,node_saved_model,node_user toneIndigo
```

## Components

### Scenario and world

- [Scenario YAMLs](https://github.com/avbiswas/navigation-mappo-rl/tree/main/configs): `configs`
- [Environment schema](https://github.com/avbiswas/navigation-mappo-rl/blob/main/nav/config_models.py): `nav/config_models.py`

### Simulation and sensing

- [Multi-agent environment](https://github.com/avbiswas/navigation-mappo-rl/blob/main/nav/environment.py): `nav/environment.py`
- [Obstacles and boundary](https://github.com/avbiswas/navigation-mappo-rl/blob/main/nav/obstacles.py): `nav/obstacles.py`
- [Geometry utilities](https://github.com/avbiswas/navigation-mappo-rl/blob/main/nav/utils.py): `nav/utils.py`
- [Ray intersections](https://github.com/avbiswas/navigation-mappo-rl/blob/main/nav/ray_intersection.py): `nav/ray_intersection.py`

### MAPPO learning

- [MAPPO trainer](https://github.com/avbiswas/navigation-mappo-rl/blob/main/rl/mappo.py): `rl/mappo.py`
- [Observation encoder](https://github.com/avbiswas/navigation-mappo-rl/blob/main/networks/actor_critic_network.py): `networks/actor_critic_network.py`
- [Gaussian actions](https://github.com/avbiswas/navigation-mappo-rl/blob/main/rl/distributions.py): `rl/distributions.py`
- [Rollout buffer](https://github.com/avbiswas/navigation-mappo-rl/blob/main/rl/rollout_buffer_with_states.py): `rl/rollout_buffer_with_states.py`

### Rendering

- [Render snapshot models](https://github.com/avbiswas/navigation-mappo-rl/blob/main/nav/renderer_models.py): `nav/renderer_models.py`
- [Live renderer](https://github.com/avbiswas/navigation-mappo-rl/blob/main/nav/live_renderer.py): `nav/live_renderer.py`

### Train and evaluate

- [Training entry point](https://github.com/avbiswas/navigation-mappo-rl/blob/main/train_mappo.py): `train_mappo.py`
- [Inference runner](https://github.com/avbiswas/navigation-mappo-rl/blob/main/inference.py): `inference.py`
- **Saved model**

### Other components

- **Experimenter**

## Connections

- Experimenter → Scenario YAMLs: selects (evidence: `README.md`)
- Scenario YAMLs → Environment schema: follows schema (evidence: `README.md`)
- Experimenter → Training entry point: starts training (evidence: `README.md`)
- Training entry point → Scenario YAMLs: loads config (evidence: `README.md`)
- Training entry point → Multi-agent environment: trains in (evidence: `train_mappo.py`)
- Training entry point → MAPPO trainer: configures (evidence: `train_mappo.py`)
- Training entry point → Observation encoder: configures (evidence: `train_mappo.py`)
- Multi-agent environment → Environment schema: uses config (evidence: `nav/environment.py`)
- Multi-agent environment → Obstacles and boundary: uses geometry (evidence: `nav/environment.py`)
- Multi-agent environment → Geometry utilities: uses utilities (evidence: `nav/environment.py`)
- Multi-agent environment → Ray intersections: computes sensing (evidence: `nav/environment.py`)
- Multi-agent environment → Render snapshot models: creates snapshots (evidence: `nav/environment.py`)
- Multi-agent environment → Live renderer: updates display (evidence: `nav/environment.py`)
- Obstacles and boundary → Geometry utilities: uses utilities (evidence: `nav/obstacles.py`)
- Ray intersections → Obstacles and boundary: intersects shapes (evidence: `nav/ray_intersection.py`)
- Ray intersections → Environment schema: uses geometry types (evidence: `nav/ray_intersection.py`)
- Render snapshot models → Environment schema: uses config types (evidence: `nav/renderer_models.py`)
- Render snapshot models → Ray intersections: uses ray results (evidence: `nav/renderer_models.py`)
- Live renderer → Render snapshot models: renders snapshots (evidence: `nav/live_renderer.py`)
- MAPPO trainer → Observation encoder: encodes observations (evidence: `rl/mappo.py`)
- MAPPO trainer → Gaussian actions: uses action distribution (evidence: `rl/mappo.py`)
- MAPPO trainer → Rollout buffer: stores rollouts (evidence: `rl/mappo.py`)
- MAPPO trainer → Multi-agent environment: collects experience (evidence: `rl/mappo.py`)
- MAPPO trainer → Saved model: saves checkpoint (evidence: `README.md`)
- Experimenter → Inference runner: starts evaluation (evidence: `README.md`)
- Inference runner → Multi-agent environment: steps simulation (evidence: `inference.py`)
- Inference runner → MAPPO trainer: loads and predicts (evidence: `inference.py`)
- Inference runner → Scenario YAMLs: selects config (evidence: `README.md`)
- Saved model → Inference runner: loads checkpoint (evidence: `README.md`)