How aerwalk/magistratura works
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: main.py HTTP and WebSocket API · robot_controller.py Robot execution · state.py Warehouse state · agent_registry.py Agent registry
Components 19
Warehouse model
- Warehouse state
web/backend/app/core/state.py - Warehouse grid
web/backend/app/core/grid.py - Pathfinding
web/backend/app/core/pathfinding.py - Robot entities
web/backend/app/entities/robot.py - UAV entity
web/backend/app/entities/uav.py
Simulation operations
- Supply and retrieval
web/backend/app/simulation/task_manager.py - Robot execution
web/backend/app/simulation/robot_controller.py - UAV scanning
web/backend/app/simulation/uav_controller.py - Shelf rebalancing
web/backend/app/simulation/rebalancer.py
Web interface
- Browser UI
web/frontend/src/app.js - HTTP and WebSocket API
web/backend/app/main.py - Session authentication
web/backend/app/auth.py
Autonomous agents
- Agent registry
web/backend/app/agent_registry.py - Robot agent
web/agents/robot/agent.py - UAV agent
web/agents/uav/agent.py
Persistence and telemetry
- TimescaleDB and Loki
web/backend/app/db/__init__.py - Prometheus metrics
web/backend/app/metrics.py - Tracing and logs
web/backend/app/obs.py
Other components
- Operator
Connections 30
- Operator → Browser UI: uses
- Browser UI → HTTP and WebSocket API: exchanges updates
- HTTP and WebSocket API → Session authentication: authenticates
web/backend/app/main.py - HTTP and WebSocket API → Warehouse state: reads and updates
web/backend/app/main.py - HTTP and WebSocket API → Supply and retrieval: dispatches tasks
web/backend/app/main.py - HTTP and WebSocket API → Robot execution: ticks robots
web/backend/app/main.py - HTTP and WebSocket API → UAV scanning: ticks UAV
web/backend/app/main.py - HTTP and WebSocket API → Shelf rebalancing: dispatches rebalance
web/backend/app/main.py - HTTP and WebSocket API → Agent registry: routes agent messages
web/backend/app/main.py - HTTP and WebSocket API → Prometheus metrics: updates metrics
web/backend/app/main.py - HTTP and WebSocket API → Tracing and logs: initializes tracing
web/backend/app/main.py - Supply and retrieval → Warehouse state: queues work
web/backend/app/simulation/task_manager.py - Supply and retrieval → Robot execution: reserves routes
web/backend/app/simulation/task_manager.py - Supply and retrieval → Pathfinding: finds paths
web/backend/app/simulation/task_manager.py - Robot execution → Warehouse state: updates inventory
web/backend/app/simulation/robot_controller.py - Robot execution → Warehouse grid: checks traversability
web/backend/app/simulation/robot_controller.py - Robot execution → Pathfinding: plans movement
web/backend/app/simulation/robot_controller.py - Robot execution → Agent registry: dispatches commands
web/backend/app/simulation/robot_controller.py - Robot execution → Prometheus metrics: records activity
web/backend/app/simulation/robot_controller.py - Robot execution → Tracing and logs: creates spans
web/backend/app/simulation/robot_controller.py - UAV scanning → Warehouse state: reads scan state
web/backend/app/simulation/uav_controller.py - UAV scanning → Agent registry: dispatches scans
web/backend/app/simulation/uav_controller.py - Shelf rebalancing → Warehouse state: moves stock
web/backend/app/simulation/rebalancer.py - Shelf rebalancing → Warehouse grid: scores shelf positions
web/backend/app/simulation/rebalancer.py - Robot entities → Warehouse grid: adds home cells
web/backend/app/entities/robot.py - Warehouse state → TimescaleDB and Loki: persists event logs
web/backend/app/core/state.py - Tracing and logs → TimescaleDB and Loki: ships warning logs
web/backend/app/obs.py - Prometheus metrics → Warehouse state: samples warehouse state
web/backend/app/metrics.py - Agent registry → Robot agent: sends robot messages
- Agent registry → UAV agent: sends UAV messages