# ardev1161/amurcore architecture

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

- Interactive diagram: https://gitdiagram.com/ardev1161/amurcore
- Repository: https://github.com/ardev1161/amurcore

## Overview

#### Purpose and runtime
Amur Core is a Qt/C++ desktop control application for communicating with an RPi-based robot running AmurClient. It presents operational UI, sends robot commands, and consumes telemetry, navigation/map, video, and sensor data. Build composition is rooted at `CMakeLists.txt`; application startup is `main.cpp`.

#### Application shell and orchestration
The main UI/controller is `AmurCore`, defined in `amurcore.h` and implemented in `amurcore.cpp`, with its Qt Designer layout in `AmurCore.ui`. It coordinates feature dialogs and subsystem objects, forming the primary boundary between user actions and robot-control services.

#### Network transport and robot sessions
The network subsystem owns connection lifecycle and robot-facing communication:
- `network/networkcontroller.h`, `network/networkcontroller.cpp`
- `network/client.h`, `network/client.cpp`
- `network/server.h`, `network/server.cpp`

`network/connectdialog.*` supplies connection UI. `network/robotrepository.*` and `network/robotentry.h` model/manage known or active robot endpoints. Client/server support indicates the application can initiate connections and expose a server-side communication role.

#### Protocol contract
Robot communication is defined through Protocol Buffers under `network/protobuf/`, including `robot.proto`, `drives.proto`, `video.proto`, `map.proto`, `navigation.proto`, `imu.proto`, and `power.proto`. `network/protobuf/CMakeLists.txt` builds generated protocol artifacts. This is the key compatibility boundary with the external AmurClient robot software; CMake gRPC setup is in `cmake/grpc.cmake`.

#### Concurrent execution model
Background processing is organized around generic worker/session abstractions:
- `threads/worker.h`, `threads/worker.cpp`
- `threads/session.h`, `threads/session.cpp`

These isolate long-running connection, input, or processing work from the Qt UI event loop. Feature-specific workers, such as `camera/calibratorworker.*` and `joystick/joystickstateworker.*`, likely feed results back through Qt’s signal/slot mechanisms.

#### Robot control, navigation, and status logic
The `logic` module translates UI/system state into robot behaviors and displays received state:
- `logic/logic.h`, `logic/logic.cpp`
- `logic/movements.h`, `logic/movements.cpp`
- `logic/system.h`, `logic/system.cpp`

Navigation is mediated by `logic/navigation_adapter.h`, with map display in `logic/map/mapwidget.*` and navigation/status dialogs in `logic/navdialog.*` and `logic/robotinfodialog.*`. These components sit between protobuf/network payloads and user-visible control/status views.

#### Camera and joystick input pipelines
Camera support includes calibration UI and calibration processing in `camera/camcalibrate.*`, `camera/calibrator.*`, and `camera/calibratorworker.*`; OpenCV is the material vision dependency. Joystick support wraps SDL-based device input and converts it into control state through `joystick/joystick.*`, `joystick/getstatebyjoy.*`, and `joystick/v_joystick_adapter.*`. Both pipelines ultimately supply robot movement/camera commands through application logic and network transport.

#### Configuration and external dependencies
`config/configprocessor.*` loads application configuration, templated by `AmurCore.cfg.in`. The runtime depends on Qt 5 (including Qt Speech), OpenCV, Protobuf/gRPC, SDL2, and PocketSphinx/SphinxBase. The robot is expected to expose camera, IMU, environmental/power sensors, wheel/hand encoders, drive motors, and camera servos through the protocol contract.

Main entry points: [`network/networkcontroller.cpp`](https://github.com/ardev1161/amurcore/blob/master/network/networkcontroller.cpp) (Network controller), [`logic/logic.cpp`](https://github.com/ardev1161/amurcore/blob/master/logic/logic.cpp) (Control logic), [`amurcore.cpp`](https://github.com/ardev1161/amurcore/blob/master/amurcore.cpp) (AmurCore shell), [`threads/session.cpp`](https://github.com/ardev1161/amurcore/blob/master/threads/session.cpp) (Worker sessions)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_desktop["Desktop application"]
  node_startup["Application startup<br/>Qt entry point<br/>[main.cpp]"]
  node_shell["AmurCore shell<br/>Qt controller<br/>[amurcore.cpp]"]
  node_layout["Main window layout<br/>Qt Designer UI<br/>[AmurCore.ui]"]
  node_connection_ui["Connection dialog<br/>Qt dialog"]
end

subgraph group_control["Control and UI features"]
  node_logic["Control logic<br/>behavior coordinator<br/>[logic.cpp]"]
  node_movement["Movement control<br/>robot control<br/>[movements.cpp]"]
  node_navigation["Navigation adapter<br/>navigation bridge"]
  node_map_ui["Map display<br/>map widget"]
  node_status_ui["Navigation and status dialogs<br/>Qt dialogs"]
end

subgraph group_transport["Robot communication"]
  node_network_controller["Network controller<br/>connection lifecycle"]
  node_robot_repository["Robot repository<br/>endpoint registry"]
  node_client["Robot client<br/>network client<br/>[client.cpp]"]
  node_server["Communication server<br/>network server<br/>[server.cpp]"]
  node_protocol["Robot protobuf contract<br/>Protobuf/gRPC API"]
end

subgraph group_pipelines["Input pipelines"]
  node_workers["Worker sessions<br/>background execution<br/>[session.cpp]"]
  node_camera["Camera calibration<br/>OpenCV pipeline"]
  node_joystick["Joystick input<br/>SDL input pipeline"]
end

node_build["CMake build<br/>build system<br/>[CMakeLists.txt]"]
node_robot{{"AmurClient robot<br/>external robot runtime"}}

node_build -->|"builds"| node_startup
node_startup -->|"starts"| node_shell
node_shell -->|"uses"| node_layout
node_shell -->|"opens"| node_connection_ui
node_shell -->|"coordinates"| node_logic
node_shell -->|"manages sessions"| node_network_controller
node_connection_ui -->|"selects endpoint"| node_robot_repository
node_robot_repository -->|"supplies endpoint"| node_network_controller
node_logic -->|"issues controls"| node_movement
node_logic -->|"adapts navigation"| node_navigation
node_navigation -->|"renders map data"| node_map_ui
node_logic -->|"updates status"| node_status_ui
node_logic -->|"sends commands"| node_network_controller
node_network_controller -->|"initiates connections"| node_client
node_network_controller -->|"hosts communication role"| node_server
node_network_controller -->|"runs work in background"| node_workers
node_client -->|"uses"| node_protocol
node_server -->|"uses"| node_protocol
node_protocol -->|"defines robot API"| node_robot
node_robot -->|"telemetry and media"| node_network_controller
node_camera -->|"calibration worker"| node_workers
node_camera -->|"supplies camera commands"| node_logic
node_joystick -->|"state worker"| node_workers
node_joystick -->|"supplies control state"| node_movement

click node_build "https://github.com/ardev1161/amurcore/blob/master/CMakeLists.txt"
click node_startup "https://github.com/ardev1161/amurcore/blob/master/main.cpp"
click node_shell "https://github.com/ardev1161/amurcore/blob/master/amurcore.cpp"
click node_layout "https://github.com/ardev1161/amurcore/blob/master/AmurCore.ui"
click node_logic "https://github.com/ardev1161/amurcore/blob/master/logic/logic.cpp"
click node_movement "https://github.com/ardev1161/amurcore/blob/master/logic/movements.cpp"
click node_navigation "https://github.com/ardev1161/amurcore/blob/master/logic/navigation_adapter.h"
click node_network_controller "https://github.com/ardev1161/amurcore/blob/master/network/networkcontroller.cpp"
click node_client "https://github.com/ardev1161/amurcore/blob/master/network/client.cpp"
click node_server "https://github.com/ardev1161/amurcore/blob/master/network/server.cpp"
click node_workers "https://github.com/ardev1161/amurcore/blob/master/threads/session.cpp"

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_startup,node_shell,node_layout,node_connection_ui toneBlue
class node_logic,node_movement,node_navigation,node_map_ui,node_status_ui toneAmber
class node_network_controller,node_robot_repository,node_client,node_server,node_protocol toneMint
class node_workers,node_camera,node_joystick toneRose
class node_build,node_robot toneNeutral
```

## Components

### Desktop application

- [Application startup](https://github.com/ardev1161/amurcore/blob/master/main.cpp): Qt entry point · `main.cpp`
- [AmurCore shell](https://github.com/ardev1161/amurcore/blob/master/amurcore.cpp): Qt controller · Primary boundary between operator actions and robot services. · `amurcore.cpp`
- [Main window layout](https://github.com/ardev1161/amurcore/blob/master/AmurCore.ui): Qt Designer UI · `AmurCore.ui`
- **Connection dialog**: Qt dialog

### Control and UI features

- [Control logic](https://github.com/ardev1161/amurcore/blob/master/logic/logic.cpp): behavior coordinator · Translates application state into robot control and received status. · `logic/logic.cpp`
- [Movement control](https://github.com/ardev1161/amurcore/blob/master/logic/movements.cpp): robot control · `logic/movements.cpp`
- [Navigation adapter](https://github.com/ardev1161/amurcore/blob/master/logic/navigation_adapter.h): navigation bridge · `logic/navigation_adapter.h`
- **Map display**: map widget
- **Navigation and status dialogs**: Qt dialogs

### Robot communication

- [Network controller](https://github.com/ardev1161/amurcore/blob/master/network/networkcontroller.cpp): connection lifecycle · Owns robot-facing connection lifecycle. · `network/networkcontroller.cpp`
- **Robot repository**: endpoint registry · Models known and active robot endpoints.
- [Robot client](https://github.com/ardev1161/amurcore/blob/master/network/client.cpp): network client · `network/client.cpp`
- [Communication server](https://github.com/ardev1161/amurcore/blob/master/network/server.cpp): network server · `network/server.cpp`
- **Robot protobuf contract**: Protobuf/gRPC API · Compatibility boundary with external AmurClient.

### Input pipelines

- [Worker sessions](https://github.com/ardev1161/amurcore/blob/master/threads/session.cpp): background execution · Keeps connection and processing work off the Qt event loop. · `threads/session.cpp`
- **Camera calibration**: OpenCV pipeline · Calibration UI and background processing.
- **Joystick input**: SDL input pipeline · Converts device input into control state.

### Other components

- [CMake build](https://github.com/ardev1161/amurcore/blob/master/CMakeLists.txt): build system · Build root and dependency composition. · `CMakeLists.txt`
- **AmurClient robot**: external robot runtime · Provides drives, navigation, video, IMU, and power telemetry.

## Connections

- CMake build → Application startup: builds
- Application startup → AmurCore shell: starts
- AmurCore shell → Main window layout: uses
- AmurCore shell → Connection dialog: opens
- AmurCore shell → Control logic: coordinates
- AmurCore shell → Network controller: manages sessions
- Connection dialog → Robot repository: selects endpoint
- Robot repository → Network controller: supplies endpoint
- Control logic → Movement control: issues controls
- Control logic → Navigation adapter: adapts navigation
- Navigation adapter → Map display: renders map data
- Control logic → Navigation and status dialogs: updates status
- Control logic → Network controller: sends commands
- Network controller → Robot client: initiates connections
- Network controller → Communication server: hosts communication role
- Network controller → Worker sessions: runs work in background
- Robot client → Robot protobuf contract: uses
- Communication server → Robot protobuf contract: uses
- Robot protobuf contract → AmurClient robot: defines robot API
- AmurClient robot → Network controller: telemetry and media
- Camera calibration → Worker sessions: calibration worker
- Camera calibration → Control logic: supplies camera commands
- Joystick input → Worker sessions: state worker
- Joystick input → Movement control: supplies control state