# swetha-arul/constraint-based-drone-route-planner architecture

> Architecture diagram of the GitHub repository swetha-arul/constraint-based-drone-route-planner, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-04-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/swetha-arul/constraint-based-drone-route-planner
- Repository: https://github.com/swetha-arul/constraint-based-drone-route-planner

## Overview

1. **Overall shape**
   - This is a single-process Python mission-planning simulator for autonomous drones, centered on a shared 3D voxel environment.
   - The code is organized as small domain modules under `src/`, with `main.py` acting as the orchestration layer rather than a reusable library entrypoint.

2. **Core runtime flow**
   - `src/main.py` wires the system together in this order: build environment → generate weather/obstacles → run planning → run preflight check → start visualization/simulation → handle mid-flight replanning if needed.
   - Most subsystems read from and mutate the same grid state, so the grid is the main integration boundary.

3. **Environment model**
   - `src/environment/grid.py` provides the 3D occupancy grid, with cells classified as free, obstacle, or no-fly.
   - `src/environment/constraints.py` defines restricted regions, specifically cuboid no-fly zones that are baked into the grid before planning begins.
   - The environment is the authoritative source for spatial legality; other modules query it rather than maintaining separate maps.

4. **Static and dynamic hazards**
   - Static hazards come from the environment setup: buildings, trees, and no-fly volumes occupy grid cells.
   - Dynamic hazards are handled as live obstacles during simulation; these can be introduced mid-flight and force replanning.
   - Weather is modeled separately from occupancy, but still affects route selection through added traversal cost.

5. **Weather subsystem**
   - `src/weather/weather_model.py` generates randomized weather zones each run, including rain, wind, and storm regions.
   - Weather does not block cells; instead it contributes step penalties that influence the planner’s cost function.
   - The README describes rain as also being visualized, indicating the weather model feeds both planning and rendering concerns.

6. **Energy and feasibility model**
   - `src/battery/battery_model.py` computes per-step energy usage using distance, payload weight, altitude change, and weather penalties.
   - This model is central to feasibility: the planner prunes any path whose cumulative energy would exceed the configured battery capacity.
   - Energy consumption is therefore not just a simulation detail; it is part of route search and mission viability.

7. **Planning subsystem**
   - `src/planner/planner.py` implements the main 3D A* search over the grid.
   - The planner is battery-constrained, meaning search nodes are discarded as soon as their projected cost exceeds the battery budget.
   - The planner is the main decision engine for the mission, producing the initial route and any later reroutes.

8. **Preflight authorization**
   - `src/decision/preflight_checker.py` acts as a GO/NO-GO gate before takeoff.
   - It checks three things: a route exists, the route is legal against the grid snapshot, and the mission length is within a fixed budget.
   - This module is a boundary between planning and execution: it prevents a visually plausible route from entering simulation if it violates constraints.

9. **Route validation**
   - `src/validation/route_validator.py` provides waypoint-by-waypoint legality checks against a grid snapshot.
   - It is used by the preflight stage and can also support live validation if the environment changes.
   - This is the repository’s explicit safety-check layer, separate from route generation.

10. **Recovery and replanning**
   - `src/recovery/replanner.py` handles mission recovery when a new obstacle appears ahead of the drone.
   - The simulation looks ahead a short distance, detects a conflict, applies a flat replanning penalty, and calls back into the planner from the current position to the goal.
   - This creates a closed-loop control path: execution can feed back into planning without restarting the entire mission.

11. **Visualization and interaction**
   - `src/visualization/simulator.py` uses PyVista to render the 3D grid, the drone, the planned spline, and the executed trail.
   - It also handles user interaction, including right-click obstacle placement that triggers the replanning path.
   - Visualization is not passive; it is part of the runtime system because it can alter the environment during simulation.

12. **System boundaries and data ownership**
   - The architecture cleanly separates concerns into environment, cost modeling, planning, validation, decision, recovery, and visualization.
   - However, these modules are tightly coupled through shared grid state and cost parameters, so the grid plus battery capacity are the key cross-cutting inputs.
   - The repo is best understood as a simulation pipeline with one authoritative world model and multiple consumers of that model.

13. **Technologies and execution context**
   - The implementation is Python 3.9+ with `numpy` for grid/data handling and `pyvista` for 3D rendering and interaction.
   - There is no indication of external services, databases, or distributed components; all behavior appears local and in-memory.
   - The architecture is therefore a self-contained scientific/simulation application rather than a server or CLI-only utility.

14. **What to emphasize in a diagram**
   - Show `main.py` as the coordinator.
   - Show a central 3D grid/environment feeding planner, validator, and simulator.
   - Show weather and battery as cost-model inputs into planning and runtime energy tracking.
   - Show preflight as a gate before simulation, and recovery as a loop from simulation back to planning when dynamic obstacles appear.

Main entry points: [`src/main.py`](https://github.com/swetha-arul/constraint-based-drone-route-planner/blob/main/src/main.py) (main.py), [`src/planner/planner.py`](https://github.com/swetha-arul/constraint-based-drone-route-planner/blob/main/src/planner/planner.py) (A* Planner), [`src/environment/grid.py`](https://github.com/swetha-arul/constraint-based-drone-route-planner/blob/main/src/environment/grid.py) (3D Grid), [`src/visualization/simulator.py`](https://github.com/swetha-arul/constraint-based-drone-route-planner/blob/main/src/visualization/simulator.py) (Simulator)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_orchestration["Orchestration"]
  node_main["main.py<br/>orchestrator<br/>[main.py]"]
end

subgraph group_environment["Environment"]
  node_grid[("3D Grid<br/>voxel world<br/>[grid.py]")]
  node_constraints["No-fly Zones<br/>spatial rules<br/>[constraints.py]"]
end

subgraph group_cost["Cost Models"]
  node_weather["Weather Model<br/>zone costs<br/>[weather_model.py]"]
  node_battery["Battery Model<br/>energy model<br/>[battery_model.py]"]
end

subgraph group_planning["Planning"]
  node_planner["A* Planner<br/>route search<br/>[planner.py]"]
  node_replanner["Replanner<br/>recovery loop<br/>[replanner.py]"]
end

subgraph group_safety["Safety"]
  node_preflight["Preflight Check<br/>go/no-go gate"]
  node_validator["Route Validator<br/>legality check<br/>[route_validator.py]"]
end

subgraph group_runtime["Runtime"]
  node_simulator["Simulator<br/>3D runtime<br/>[simulator.py]"]
end

node_main -->|"builds"| node_grid
node_main -->|"applies"| node_constraints
node_main -->|"generates"| node_weather
node_main -->|"configures"| node_battery
node_main -->|"plans"| node_planner
node_main -->|"checks"| node_preflight
node_main -->|"starts"| node_simulator
node_planner -->|"reads"| node_grid
node_planner -->|"costs"| node_weather
node_planner -->|"budgets"| node_battery
node_preflight -->|"uses"| node_validator
node_preflight -->|"verifies"| node_grid
node_simulator -->|"renders"| node_grid
node_simulator -->|"requests"| node_planner
node_replanner -->|"calls"| node_planner
node_replanner -->|"updates"| node_grid
node_simulator -->|"detects"| node_replanner
node_weather -->|"visualizes"| node_simulator
node_battery -->|"constrains"| node_planner
node_validator -->|"checks"| node_grid

click node_main "https://github.com/swetha-arul/constraint-based-drone-route-planner/blob/main/src/main.py"
click node_grid "https://github.com/swetha-arul/constraint-based-drone-route-planner/blob/main/src/environment/grid.py"
click node_constraints "https://github.com/swetha-arul/constraint-based-drone-route-planner/blob/main/src/environment/constraints.py"
click node_weather "https://github.com/swetha-arul/constraint-based-drone-route-planner/blob/main/src/weather/weather_model.py"
click node_battery "https://github.com/swetha-arul/constraint-based-drone-route-planner/blob/main/src/battery/battery_model.py"
click node_planner "https://github.com/swetha-arul/constraint-based-drone-route-planner/blob/main/src/planner/planner.py"
click node_replanner "https://github.com/swetha-arul/constraint-based-drone-route-planner/blob/main/src/recovery/replanner.py"
click node_preflight "https://github.com/swetha-arul/constraint-based-drone-route-planner/blob/main/src/decision/preflight_checker.py"
click node_validator "https://github.com/swetha-arul/constraint-based-drone-route-planner/blob/main/src/validation/route_validator.py"
click node_simulator "https://github.com/swetha-arul/constraint-based-drone-route-planner/blob/main/src/visualization/simulator.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 toneBlue
class node_grid,node_constraints toneAmber
class node_weather,node_battery toneMint
class node_planner,node_replanner toneRose
class node_preflight,node_validator toneIndigo
class node_simulator toneTeal
```

## Components

### Orchestration

Top-level mission flow and runtime coordination.

- [main.py](https://github.com/swetha-arul/constraint-based-drone-route-planner/blob/main/src/main.py): orchestrator · Wires environment setup, planning, preflight, simulation, and replanning. · `src/main.py`

### Environment

Shared 3D world model and spatial constraints.

- [3D Grid](https://github.com/swetha-arul/constraint-based-drone-route-planner/blob/main/src/environment/grid.py): voxel world · Authoritative occupancy map for free, obstacle, and no-fly cells. · `src/environment/grid.py`
- [No-fly Zones](https://github.com/swetha-arul/constraint-based-drone-route-planner/blob/main/src/environment/constraints.py): spatial rules · Cuboid restricted regions baked into the grid before planning. · `src/environment/constraints.py`

### Cost Models

Weather and energy models that influence route feasibility.

- [Weather Model](https://github.com/swetha-arul/constraint-based-drone-route-planner/blob/main/src/weather/weather_model.py): zone costs · Generates rain, wind, and storm regions that add traversal penalty. · `src/weather/weather_model.py`
- [Battery Model](https://github.com/swetha-arul/constraint-based-drone-route-planner/blob/main/src/battery/battery_model.py): energy model · Computes per-step energy use from distance, payload, altitude, and weather. · `src/battery/battery_model.py`

### Planning

Route search and recovery when the mission state changes.

- [A* Planner](https://github.com/swetha-arul/constraint-based-drone-route-planner/blob/main/src/planner/planner.py): route search · Battery-constrained 3D A* search that produces initial and rerouted paths. · `src/planner/planner.py`
- [Replanner](https://github.com/swetha-arul/constraint-based-drone-route-planner/blob/main/src/recovery/replanner.py): recovery loop · Replans from the current position when a new obstacle blocks the path. · `src/recovery/replanner.py`

### Safety

Preflight and route legality checks.

- [Preflight Check](https://github.com/swetha-arul/constraint-based-drone-route-planner/blob/main/src/decision/preflight_checker.py): go/no-go gate · Verifies route existence, legality, and mission length before takeoff. · `src/decision/preflight_checker.py`
- [Route Validator](https://github.com/swetha-arul/constraint-based-drone-route-planner/blob/main/src/validation/route_validator.py): legality check · Checks waypoints against a grid snapshot for route safety. · `src/validation/route_validator.py`

### Runtime

Simulation and interactive execution loop.

- [Simulator](https://github.com/swetha-arul/constraint-based-drone-route-planner/blob/main/src/visualization/simulator.py): 3D runtime · Renders the grid, drone, planned path, and executed trail in PyVista. · `src/visualization/simulator.py`

## Connections

- main.py → 3D Grid: builds · Creates the shared spatial world model.
- main.py → No-fly Zones: applies · Loads restricted regions into the environment.
- main.py → Weather Model: generates · Creates per-run weather zones.
- main.py → Battery Model: configures · Supplies battery budget and consumption assumptions.
- main.py → A* Planner: plans · Runs route search before execution.
- main.py → Preflight Check: checks · Performs GO/NO-GO validation before takeoff.
- main.py → Simulator: starts · Launches the visualization and execution loop.
- A* Planner → 3D Grid: reads · Searches over the occupancy grid.
- A* Planner → Weather Model: costs · Uses weather penalties in path scoring.
- A* Planner → Battery Model: budgets · Prunes paths that exceed energy capacity.
- Preflight Check → Route Validator: uses · Delegates route legality checks.
- Preflight Check → 3D Grid: verifies · Checks the planned route against the latest grid snapshot.
- Simulator → 3D Grid: renders · Visualizes obstacles, no-fly cells, and dynamic changes.
- Simulator → A* Planner: requests · Triggers replanning when the path is obstructed.
- Replanner → A* Planner: calls · Reuses the planner from the current drone position.
- Replanner → 3D Grid: updates · Responds to newly introduced obstacles.
- Simulator → Replanner: detects · Looks ahead and initiates recovery on conflict.
- Weather Model → Simulator: visualizes · Feeds weather display in the runtime view.
- Battery Model → A* Planner: constrains · Shapes feasible route search space.
- Route Validator → 3D Grid: checks · Evaluates waypoints against spatial legality.
