# nerrazzuri/nexus-warden-patrol architecture

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

- Interactive diagram: https://gitdiagram.com/nerrazzuri/nexus-warden-patrol
- Repository: https://github.com/nerrazzuri/nexus-warden-patrol

## Overview

Nexus Warden is a quadruped-robot security patrol system. Site operators configure maps, routes, and schedules; the site service coordinates patrols and alerts, while robot agents execute missions and report status/evidence. Localization and hardware adapters support execution, and mobile and web clients provide operator interfaces. The README documents these product-level relationships; source excerpts and the index show selected internal wiring. Other unsampled connections are omitted rather than inferred.

Main entry points: [`packages/robot-agent/src/nexwar_agent/main.py`](https://github.com/nerrazzuri/nexus-warden-patrol/blob/master/packages/robot-agent/src/nexwar_agent/main.py) (Robot agent), [`packages/site-node/src/nexwar_site/main.py`](https://github.com/nerrazzuri/nexus-warden-patrol/blob/master/packages/site-node/src/nexwar_site/main.py) (Site service), [`packages/site-node/src/nexwar_site/routes.py`](https://github.com/nerrazzuri/nexus-warden-patrol/blob/master/packages/site-node/src/nexwar_site/routes.py) (Routes and schedules), [`packages/contract/src/nexwar_contract`](https://github.com/nerrazzuri/nexus-warden-patrol/tree/master/packages/contract/src/nexwar_contract) (Wire and mission contracts)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_site["Site operations"]
  node_site_service["Site service<br/>[main.py]"]
  node_route_schedule["Routes and schedules<br/>[routes.py]"]
  node_site_maps["Map management<br/>[maps.py]"]
  node_site_evidence["Evidence and alerts<br/>[evidence.py]"]
  node_site_db[("Site database<br/>[db.py]")]
end

subgraph group_robot["Robot runtime"]
  node_agent["Robot agent<br/>[main.py]"]
  node_mission_engine["Mission execution<br/>[machine.py]"]
  node_homing["Homing and charging<br/>[homing.py]"]
  node_agent_mapping["Robot mapping<br/>[mapping.py]"]
  node_agent_storage["Run storage and upload<br/>[storage.py]"]
end

subgraph group_nav["Navigation and hardware"]
  node_localizer["Localization<br/>[core.py]"]
  node_localizer_entry["Localizer service<br/>[main.py]"]
  node_d1_adapter["D1 Max adapter"]
  node_sim_adapter["Simulation adapter"]
  node_motion["Motion control"]
end

subgraph group_clients["Operator clients"]
  node_web_console["Web console"]
  node_mobile_app["Mobile app"]
end

subgraph group_shared["Shared contracts"]
  node_contracts["Wire and mission contracts"]
  node_patrol_protocol["Navigation protocol<br/>[nav_types.py]"]
  node_patrol_mapping["Mapping application<br/>[mapping.py]"]
  node_patrol_processes["Process management<br/>[procs.py]"]
end

node_operator(("Site operator"))

node_operator -->|"operates"| node_web_console
node_operator -->|"uses"| node_mobile_app
node_web_console -->|"requests site services"| node_site_service
node_mobile_app -->|"connects to site"| node_site_service
node_site_service -->|"manages patrol plans"| node_route_schedule
node_site_service -->|"provides map operations"| node_site_maps
node_site_service -->|"handles evidence"| node_site_evidence
node_site_service -->|"uses database"| node_site_db
node_route_schedule -->|"checks route maps"| node_site_maps
node_route_schedule -->|"parses mission formats"| node_contracts
node_site_service -->|"dispatches patrols"| node_agent
node_agent -->|"exchanges messages"| node_contracts
node_agent -->|"assembles runtime"| node_mission_engine
node_mission_engine -.->|"uses homing behavior"| node_homing
node_agent -->|"supports mapping"| node_agent_mapping
node_agent -.->|"stores run data"| node_agent_storage
node_agent -->|"uses localization"| node_localizer
node_localizer_entry -->|"feeds estimates"| node_localizer
node_localizer_entry -->|"bridges localization"| node_patrol_protocol
node_agent -->|"adapts D1 Max"| node_d1_adapter
node_agent -->|"supports simulation"| node_sim_adapter
node_agent -->|"uses motion bypass"| node_motion
node_agent -->|"uses navigation types"| node_patrol_protocol
node_patrol_mapping -.->|"starts mapping processes"| node_patrol_processes
node_agent_mapping -->|"uses map formats"| node_contracts

click node_site_service "https://github.com/nerrazzuri/nexus-warden-patrol/blob/master/packages/site-node/src/nexwar_site/main.py"
click node_route_schedule "https://github.com/nerrazzuri/nexus-warden-patrol/blob/master/packages/site-node/src/nexwar_site/routes.py"
click node_site_maps "https://github.com/nerrazzuri/nexus-warden-patrol/blob/master/packages/site-node/src/nexwar_site/maps.py"
click node_site_evidence "https://github.com/nerrazzuri/nexus-warden-patrol/blob/master/packages/site-node/src/nexwar_site/evidence.py"
click node_site_db "https://github.com/nerrazzuri/nexus-warden-patrol/blob/master/packages/site-node/src/nexwar_site/db.py"
click node_web_console "https://github.com/nerrazzuri/nexus-warden-patrol/tree/master/web/console/src"
click node_mobile_app "https://github.com/nerrazzuri/nexus-warden-patrol/tree/master/mobile"
click node_agent "https://github.com/nerrazzuri/nexus-warden-patrol/blob/master/packages/robot-agent/src/nexwar_agent/main.py"
click node_mission_engine "https://github.com/nerrazzuri/nexus-warden-patrol/blob/master/packages/robot-agent/src/nexwar_agent/engine/machine.py"
click node_homing "https://github.com/nerrazzuri/nexus-warden-patrol/blob/master/packages/robot-agent/src/nexwar_agent/engine/homing.py"
click node_agent_mapping "https://github.com/nerrazzuri/nexus-warden-patrol/blob/master/packages/robot-agent/src/nexwar_agent/mapping.py"
click node_agent_storage "https://github.com/nerrazzuri/nexus-warden-patrol/blob/master/packages/robot-agent/src/nexwar_agent/engine/storage.py"
click node_localizer "https://github.com/nerrazzuri/nexus-warden-patrol/blob/master/packages/localizer/src/nexwar_localizer/core.py"
click node_localizer_entry "https://github.com/nerrazzuri/nexus-warden-patrol/blob/master/packages/localizer/src/nexwar_localizer/main.py"
click node_d1_adapter "https://github.com/nerrazzuri/nexus-warden-patrol/tree/master/packages/adapter-d1max/src/nexwar_adapter_d1max"
click node_sim_adapter "https://github.com/nerrazzuri/nexus-warden-patrol/tree/master/packages/adapter-sim/src/nexwar_adapter_sim"
click node_motion "https://github.com/nerrazzuri/nexus-warden-patrol/tree/master/motion"
click node_contracts "https://github.com/nerrazzuri/nexus-warden-patrol/tree/master/packages/contract/src/nexwar_contract"
click node_patrol_protocol "https://github.com/nerrazzuri/nexus-warden-patrol/blob/master/src/nexwar_patrol/protocol/nav_types.py"
click node_patrol_mapping "https://github.com/nerrazzuri/nexus-warden-patrol/blob/master/src/nexwar_patrol/app/mapping.py"
click node_patrol_processes "https://github.com/nerrazzuri/nexus-warden-patrol/blob/master/src/nexwar_patrol/app/procs.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_site_service,node_route_schedule,node_site_maps,node_site_evidence,node_site_db toneBlue
class node_agent,node_mission_engine,node_homing,node_agent_mapping,node_agent_storage toneAmber
class node_localizer,node_localizer_entry,node_d1_adapter,node_sim_adapter,node_motion toneMint
class node_web_console,node_mobile_app toneRose
class node_contracts,node_patrol_protocol,node_patrol_mapping,node_patrol_processes,node_operator toneIndigo
```

## Components

### Site operations

- [Site service](https://github.com/nerrazzuri/nexus-warden-patrol/blob/master/packages/site-node/src/nexwar_site/main.py): `packages/site-node/src/nexwar_site/main.py`
- [Routes and schedules](https://github.com/nerrazzuri/nexus-warden-patrol/blob/master/packages/site-node/src/nexwar_site/routes.py): `packages/site-node/src/nexwar_site/routes.py`
- [Map management](https://github.com/nerrazzuri/nexus-warden-patrol/blob/master/packages/site-node/src/nexwar_site/maps.py): `packages/site-node/src/nexwar_site/maps.py`
- [Evidence and alerts](https://github.com/nerrazzuri/nexus-warden-patrol/blob/master/packages/site-node/src/nexwar_site/evidence.py): `packages/site-node/src/nexwar_site/evidence.py`
- [Site database](https://github.com/nerrazzuri/nexus-warden-patrol/blob/master/packages/site-node/src/nexwar_site/db.py): `packages/site-node/src/nexwar_site/db.py`

### Robot runtime

- [Robot agent](https://github.com/nerrazzuri/nexus-warden-patrol/blob/master/packages/robot-agent/src/nexwar_agent/main.py): `packages/robot-agent/src/nexwar_agent/main.py`
- [Mission execution](https://github.com/nerrazzuri/nexus-warden-patrol/blob/master/packages/robot-agent/src/nexwar_agent/engine/machine.py): `packages/robot-agent/src/nexwar_agent/engine/machine.py`
- [Homing and charging](https://github.com/nerrazzuri/nexus-warden-patrol/blob/master/packages/robot-agent/src/nexwar_agent/engine/homing.py): `packages/robot-agent/src/nexwar_agent/engine/homing.py`
- [Robot mapping](https://github.com/nerrazzuri/nexus-warden-patrol/blob/master/packages/robot-agent/src/nexwar_agent/mapping.py): `packages/robot-agent/src/nexwar_agent/mapping.py`
- [Run storage and upload](https://github.com/nerrazzuri/nexus-warden-patrol/blob/master/packages/robot-agent/src/nexwar_agent/engine/storage.py): `packages/robot-agent/src/nexwar_agent/engine/storage.py`

### Navigation and hardware

- [Localization](https://github.com/nerrazzuri/nexus-warden-patrol/blob/master/packages/localizer/src/nexwar_localizer/core.py): `packages/localizer/src/nexwar_localizer/core.py`
- [Localizer service](https://github.com/nerrazzuri/nexus-warden-patrol/blob/master/packages/localizer/src/nexwar_localizer/main.py): `packages/localizer/src/nexwar_localizer/main.py`
- [D1 Max adapter](https://github.com/nerrazzuri/nexus-warden-patrol/tree/master/packages/adapter-d1max/src/nexwar_adapter_d1max): `packages/adapter-d1max/src/nexwar_adapter_d1max`
- [Simulation adapter](https://github.com/nerrazzuri/nexus-warden-patrol/tree/master/packages/adapter-sim/src/nexwar_adapter_sim): `packages/adapter-sim/src/nexwar_adapter_sim`
- [Motion control](https://github.com/nerrazzuri/nexus-warden-patrol/tree/master/motion): `motion`

### Operator clients

- [Web console](https://github.com/nerrazzuri/nexus-warden-patrol/tree/master/web/console/src): `web/console/src`
- [Mobile app](https://github.com/nerrazzuri/nexus-warden-patrol/tree/master/mobile): `mobile`

### Shared contracts

- [Wire and mission contracts](https://github.com/nerrazzuri/nexus-warden-patrol/tree/master/packages/contract/src/nexwar_contract): `packages/contract/src/nexwar_contract`
- [Navigation protocol](https://github.com/nerrazzuri/nexus-warden-patrol/blob/master/src/nexwar_patrol/protocol/nav_types.py): `src/nexwar_patrol/protocol/nav_types.py`
- [Mapping application](https://github.com/nerrazzuri/nexus-warden-patrol/blob/master/src/nexwar_patrol/app/mapping.py): `src/nexwar_patrol/app/mapping.py`
- [Process management](https://github.com/nerrazzuri/nexus-warden-patrol/blob/master/src/nexwar_patrol/app/procs.py): `src/nexwar_patrol/app/procs.py`

### Other components

- **Site operator**

## Connections

- Site operator → Web console: operates (evidence: `README.md`)
- Site operator → Mobile app: uses (evidence: `README.md`)
- Web console → Site service: requests site services (evidence: `README.md`)
- Mobile app → Site service: connects to site (evidence: `README.md`)
- Site service → Routes and schedules: manages patrol plans (evidence: `packages/site-node/src/nexwar_site/main.py`)
- Site service → Map management: provides map operations (evidence: `packages/site-node/src/nexwar_site/main.py`)
- Site service → Evidence and alerts: handles evidence (evidence: `packages/site-node/src/nexwar_site/main.py`)
- Site service → Site database: uses database (evidence: `packages/site-node/src/nexwar_site/main.py`)
- Routes and schedules → Map management: checks route maps (evidence: `packages/site-node/src/nexwar_site/routes.py`)
- Routes and schedules → Wire and mission contracts: parses mission formats (evidence: `packages/site-node/src/nexwar_site/routes.py`)
- Site service → Robot agent: dispatches patrols (evidence: `README.md`)
- Robot agent → Wire and mission contracts: exchanges messages (evidence: `README.md`)
- Robot agent → Mission execution: assembles runtime
- Mission execution → Homing and charging: uses homing behavior
- Robot agent → Robot mapping: supports mapping (evidence: `README.md`)
- Robot agent → Run storage and upload: stores run data
- Robot agent → Localization: uses localization (evidence: `README.md`)
- Localizer service → Localization: feeds estimates (evidence: `packages/localizer/src/nexwar_localizer/main.py`)
- Localizer service → Navigation protocol: bridges localization (evidence: `packages/localizer/src/nexwar_localizer/main.py`)
- Robot agent → D1 Max adapter: adapts D1 Max (evidence: `README.md`)
- Robot agent → Simulation adapter: supports simulation (evidence: `README.md`)
- Robot agent → Motion control: uses motion bypass (evidence: `README.md`)
- Robot agent → Navigation protocol: uses navigation types (evidence: `packages/robot-agent/src/nexwar_agent/main.py`)
- Mapping application → Process management: starts mapping processes (evidence: `src/nexwar_patrol/app/mapping.py`)
- Robot mapping → Wire and mission contracts: uses map formats (evidence: `packages/robot-agent/src/nexwar_agent/mapping.py`)