# aerwalk/magistratura architecture

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

- Interactive diagram: https://gitdiagram.com/aerwalk/magistratura
- Repository: https://github.com/aerwalk/magistratura

## Overview

MagSim is presented in the README as a warehouse-goods simulation; the repository also contains a web-based deployment with a FastAPI backend, browser client and robot/UAV agents. The central web workflow is warehouse state and task management, robot execution, and browser-visible simulation updates. The README documents labeled and unlabeled supply, retrieval, rebalance, fleet/material/map editing and Excel export, but describes a separate PyQt application whose source is not in this tree. Web runtime excerpts are partial, so uncertain browser and agent message flows are not asserted as verified calls.

Main entry points: [`web/backend/app/main.py`](https://github.com/aerwalk/magistratura/blob/master/web/backend/app/main.py) (HTTP and WebSocket API), [`web/backend/app/simulation/robot_controller.py`](https://github.com/aerwalk/magistratura/blob/master/web/backend/app/simulation/robot_controller.py) (Robot execution), [`web/backend/app/core/state.py`](https://github.com/aerwalk/magistratura/blob/master/web/backend/app/core/state.py) (Warehouse state), [`web/backend/app/agent_registry.py`](https://github.com/aerwalk/magistratura/blob/master/web/backend/app/agent_registry.py) (Agent registry)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_warehouse["Warehouse model"]
  node_state[("Warehouse state<br/>[state.py]")]
  node_grid["Warehouse grid<br/>[grid.py]"]
  node_routing["Pathfinding<br/>[pathfinding.py]"]
  node_robot_model["Robot entities<br/>[robot.py]"]
  node_uav_model["UAV entity<br/>[uav.py]"]
end

subgraph group_operations["Simulation operations"]
  node_tasks["Supply and retrieval<br/>[task_manager.py]"]
  node_robot_control["Robot execution"]
  node_uav_control["UAV scanning<br/>[uav_controller.py]"]
  node_rebalance["Shelf rebalancing<br/>[rebalancer.py]"]
end

subgraph group_interface["Web interface"]
  node_browser["Browser UI<br/>[app.js]"]
  node_api["HTTP and WebSocket API<br/>[main.py]"]
  node_auth["Session authentication<br/>[auth.py]"]
end

subgraph group_agents["Autonomous agents"]
  node_registry["Agent registry<br/>[agent_registry.py]"]
  node_robot_agent["Robot agent<br/>[agent.py]"]
  node_uav_agent["UAV agent<br/>[agent.py]"]
end

subgraph group_telemetry["Persistence and telemetry"]
  node_database[("TimescaleDB and Loki<br/>[__init__.py]")]
  node_metrics["Prometheus metrics<br/>[metrics.py]"]
  node_observability["Tracing and logs<br/>[obs.py]"]
end

node_operator(("Operator"))

node_operator -.->|"uses"| node_browser
node_browser -.->|"exchanges updates"| node_api
node_api -->|"authenticates"| node_auth
node_api -->|"reads and updates"| node_state
node_api -->|"dispatches tasks"| node_tasks
node_api -->|"ticks robots"| node_robot_control
node_api -->|"ticks UAV"| node_uav_control
node_api -->|"dispatches rebalance"| node_rebalance
node_api -->|"routes agent messages"| node_registry
node_api -->|"updates metrics"| node_metrics
node_api -->|"initializes tracing"| node_observability
node_tasks -->|"queues work"| node_state
node_tasks -->|"reserves routes"| node_robot_control
node_tasks -->|"finds paths"| node_routing
node_robot_control -->|"updates inventory"| node_state
node_robot_control -->|"checks traversability"| node_grid
node_robot_control -->|"plans movement"| node_routing
node_robot_control -->|"dispatches commands"| node_registry
node_robot_control -->|"records activity"| node_metrics
node_robot_control -->|"creates spans"| node_observability
node_uav_control -->|"reads scan state"| node_state
node_uav_control -->|"dispatches scans"| node_registry
node_rebalance -->|"moves stock"| node_state
node_rebalance -->|"scores shelf positions"| node_grid
node_robot_model -->|"adds home cells"| node_grid
node_state -->|"persists event logs"| node_database
node_observability -->|"ships warning logs"| node_database
node_metrics -->|"samples warehouse state"| node_state
node_registry -.->|"sends robot messages"| node_robot_agent
node_registry -.->|"sends UAV messages"| node_uav_agent

click node_browser "https://github.com/aerwalk/magistratura/blob/master/web/frontend/src/app.js"
click node_api "https://github.com/aerwalk/magistratura/blob/master/web/backend/app/main.py"
click node_auth "https://github.com/aerwalk/magistratura/blob/master/web/backend/app/auth.py"
click node_state "https://github.com/aerwalk/magistratura/blob/master/web/backend/app/core/state.py"
click node_grid "https://github.com/aerwalk/magistratura/blob/master/web/backend/app/core/grid.py"
click node_routing "https://github.com/aerwalk/magistratura/blob/master/web/backend/app/core/pathfinding.py"
click node_robot_model "https://github.com/aerwalk/magistratura/blob/master/web/backend/app/entities/robot.py"
click node_uav_model "https://github.com/aerwalk/magistratura/blob/master/web/backend/app/entities/uav.py"
click node_tasks "https://github.com/aerwalk/magistratura/blob/master/web/backend/app/simulation/task_manager.py"
click node_robot_control "https://github.com/aerwalk/magistratura/blob/master/web/backend/app/simulation/robot_controller.py"
click node_uav_control "https://github.com/aerwalk/magistratura/blob/master/web/backend/app/simulation/uav_controller.py"
click node_rebalance "https://github.com/aerwalk/magistratura/blob/master/web/backend/app/simulation/rebalancer.py"
click node_registry "https://github.com/aerwalk/magistratura/blob/master/web/backend/app/agent_registry.py"
click node_robot_agent "https://github.com/aerwalk/magistratura/blob/master/web/agents/robot/agent.py"
click node_uav_agent "https://github.com/aerwalk/magistratura/blob/master/web/agents/uav/agent.py"
click node_database "https://github.com/aerwalk/magistratura/blob/master/web/backend/app/db/__init__.py"
click node_metrics "https://github.com/aerwalk/magistratura/blob/master/web/backend/app/metrics.py"
click node_observability "https://github.com/aerwalk/magistratura/blob/master/web/backend/app/obs.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_state,node_grid,node_routing,node_robot_model,node_uav_model toneBlue
class node_tasks,node_robot_control,node_uav_control,node_rebalance toneAmber
class node_browser,node_api,node_auth toneMint
class node_registry,node_robot_agent,node_uav_agent toneRose
class node_database,node_metrics,node_observability,node_operator toneIndigo
```

## Components

### Warehouse model

- [Warehouse state](https://github.com/aerwalk/magistratura/blob/master/web/backend/app/core/state.py): `web/backend/app/core/state.py`
- [Warehouse grid](https://github.com/aerwalk/magistratura/blob/master/web/backend/app/core/grid.py): `web/backend/app/core/grid.py`
- [Pathfinding](https://github.com/aerwalk/magistratura/blob/master/web/backend/app/core/pathfinding.py): `web/backend/app/core/pathfinding.py`
- [Robot entities](https://github.com/aerwalk/magistratura/blob/master/web/backend/app/entities/robot.py): `web/backend/app/entities/robot.py`
- [UAV entity](https://github.com/aerwalk/magistratura/blob/master/web/backend/app/entities/uav.py): `web/backend/app/entities/uav.py`

### Simulation operations

- [Supply and retrieval](https://github.com/aerwalk/magistratura/blob/master/web/backend/app/simulation/task_manager.py): `web/backend/app/simulation/task_manager.py`
- [Robot execution](https://github.com/aerwalk/magistratura/blob/master/web/backend/app/simulation/robot_controller.py): `web/backend/app/simulation/robot_controller.py`
- [UAV scanning](https://github.com/aerwalk/magistratura/blob/master/web/backend/app/simulation/uav_controller.py): `web/backend/app/simulation/uav_controller.py`
- [Shelf rebalancing](https://github.com/aerwalk/magistratura/blob/master/web/backend/app/simulation/rebalancer.py): `web/backend/app/simulation/rebalancer.py`

### Web interface

- [Browser UI](https://github.com/aerwalk/magistratura/blob/master/web/frontend/src/app.js): `web/frontend/src/app.js`
- [HTTP and WebSocket API](https://github.com/aerwalk/magistratura/blob/master/web/backend/app/main.py): `web/backend/app/main.py`
- [Session authentication](https://github.com/aerwalk/magistratura/blob/master/web/backend/app/auth.py): `web/backend/app/auth.py`

### Autonomous agents

- [Agent registry](https://github.com/aerwalk/magistratura/blob/master/web/backend/app/agent_registry.py): `web/backend/app/agent_registry.py`
- [Robot agent](https://github.com/aerwalk/magistratura/blob/master/web/agents/robot/agent.py): `web/agents/robot/agent.py`
- [UAV agent](https://github.com/aerwalk/magistratura/blob/master/web/agents/uav/agent.py): `web/agents/uav/agent.py`

### Persistence and telemetry

- [TimescaleDB and Loki](https://github.com/aerwalk/magistratura/blob/master/web/backend/app/db/__init__.py): `web/backend/app/db/__init__.py`
- [Prometheus metrics](https://github.com/aerwalk/magistratura/blob/master/web/backend/app/metrics.py): `web/backend/app/metrics.py`
- [Tracing and logs](https://github.com/aerwalk/magistratura/blob/master/web/backend/app/obs.py): `web/backend/app/obs.py`

### Other components

- **Operator**

## Connections

- Operator → Browser UI: uses
- Browser UI → HTTP and WebSocket API: exchanges updates
- HTTP and WebSocket API → Session authentication: authenticates (evidence: `web/backend/app/main.py`)
- HTTP and WebSocket API → Warehouse state: reads and updates (evidence: `web/backend/app/main.py`)
- HTTP and WebSocket API → Supply and retrieval: dispatches tasks (evidence: `web/backend/app/main.py`)
- HTTP and WebSocket API → Robot execution: ticks robots (evidence: `web/backend/app/main.py`)
- HTTP and WebSocket API → UAV scanning: ticks UAV (evidence: `web/backend/app/main.py`)
- HTTP and WebSocket API → Shelf rebalancing: dispatches rebalance (evidence: `web/backend/app/main.py`)
- HTTP and WebSocket API → Agent registry: routes agent messages (evidence: `web/backend/app/main.py`)
- HTTP and WebSocket API → Prometheus metrics: updates metrics (evidence: `web/backend/app/main.py`)
- HTTP and WebSocket API → Tracing and logs: initializes tracing (evidence: `web/backend/app/main.py`)
- Supply and retrieval → Warehouse state: queues work (evidence: `web/backend/app/simulation/task_manager.py`)
- Supply and retrieval → Robot execution: reserves routes (evidence: `web/backend/app/simulation/task_manager.py`)
- Supply and retrieval → Pathfinding: finds paths (evidence: `web/backend/app/simulation/task_manager.py`)
- Robot execution → Warehouse state: updates inventory (evidence: `web/backend/app/simulation/robot_controller.py`)
- Robot execution → Warehouse grid: checks traversability (evidence: `web/backend/app/simulation/robot_controller.py`)
- Robot execution → Pathfinding: plans movement (evidence: `web/backend/app/simulation/robot_controller.py`)
- Robot execution → Agent registry: dispatches commands (evidence: `web/backend/app/simulation/robot_controller.py`)
- Robot execution → Prometheus metrics: records activity (evidence: `web/backend/app/simulation/robot_controller.py`)
- Robot execution → Tracing and logs: creates spans (evidence: `web/backend/app/simulation/robot_controller.py`)
- UAV scanning → Warehouse state: reads scan state (evidence: `web/backend/app/simulation/uav_controller.py`)
- UAV scanning → Agent registry: dispatches scans (evidence: `web/backend/app/simulation/uav_controller.py`)
- Shelf rebalancing → Warehouse state: moves stock (evidence: `web/backend/app/simulation/rebalancer.py`)
- Shelf rebalancing → Warehouse grid: scores shelf positions (evidence: `web/backend/app/simulation/rebalancer.py`)
- Robot entities → Warehouse grid: adds home cells (evidence: `web/backend/app/entities/robot.py`)
- Warehouse state → TimescaleDB and Loki: persists event logs (evidence: `web/backend/app/core/state.py`)
- Tracing and logs → TimescaleDB and Loki: ships warning logs (evidence: `web/backend/app/obs.py`)
- Prometheus metrics → Warehouse state: samples warehouse state (evidence: `web/backend/app/metrics.py`)
- Agent registry → Robot agent: sends robot messages
- Agent registry → UAV agent: sends UAV messages
