# armaan-dot/nora architecture

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

- Interactive diagram: https://gitdiagram.com/armaan-dot/nora
- Repository: https://github.com/armaan-dot/nora
- Video tour (about a minute): https://gitdiagram.com/armaan-dot/nora/video

## Overview

NORA turns spoken robot commands into structured intents, scores candidate actions for usefulness and physical feasibility, plans a skill sequence, and executes it through ROS 2. The principal path is Human → NLU → Intent → Affordance scoring → Orchestrator → primitive skills → MoveIt/controllers → robot or simulator. The repository also contains a replaceable fine-tuning pipeline and simulation integrations. Several ROS nodes and interfaces are documented but unsampled, so those links are shown only where README or source explicitly supports them.

Main entry points: [`ros2_ws/src/nora_orchestrator/nora_orchestrator/orchestrator_node.py`](https://github.com/armaan-dot/nora/blob/main/ros2_ws/src/nora_orchestrator/nora_orchestrator/orchestrator_node.py) (Orchestrator Node), [`ros2_ws/src/nora_affordance`](https://github.com/armaan-dot/nora/tree/main/ros2_ws/src/nora_affordance) (Affordance Service), [`ros2_ws/src/nora_nlu_node/nora_nlu_node/nlu_node.py`](https://github.com/armaan-dot/nora/blob/main/ros2_ws/src/nora_nlu_node/nora_nlu_node/nlu_node.py) (NLU Node), [`ros2_ws/src/nora_nlu_node/nora_nlu_node/local_parser.py`](https://github.com/armaan-dot/nora/blob/main/ros2_ws/src/nora_nlu_node/nora_nlu_node/local_parser.py) (Local Parser)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_language["Language Understanding"]
  node_nlu_node["NLU Node<br/>[nlu_node.py]"]
  node_mock_parser["Mock Parser<br/>[mock_parser.py]"]
  node_local_parser["Local Parser<br/>[local_parser.py]"]
  node_intent["Structured Intent<br/>[intent.py]"]
  node_ml_data["NLU Data Pipeline"]
  node_lora_model["LoRA Model<br/>[lora_model.py]"]
end

subgraph group_reasoning["Planning and Scoring"]
  node_affordance_node["Affordance Service"]
  node_usefulness["Usefulness Scorer<br/>[llm_usefulness.py]"]
  node_feasibility["Feasibility Scorers"]
  node_fusion["Score Fusion<br/>[fusion.py]"]
  node_planner["Skill Planner<br/>[planner.py]"]
  node_skill_registry["Skill Registry<br/>[skills.py]"]
end

subgraph group_orchestration["ROS Orchestration"]
  node_orchestrator["Orchestrator Node"]
  node_state_machine["Task State Machine<br/>[state_machine.py]"]
  node_perception["Object Perception"]
end

subgraph group_execution["Robot Execution"]
  node_skills["Primitive Skills"]
  node_base_skill["Skill Action Base<br/>[base_skill.py]"]
  node_moveit["MoveIt 2"]
  node_controllers["ROS Controllers"]
  node_robot["Robot Arm"]
end

subgraph group_simulation["Simulation Targets"]
  node_gazebo["Gazebo Simulation<br/>[gazebo.launch.py]"]
  node_isaac["Isaac Simulation"]
end

node_human(("Human Operator"))

node_human -->|"sends text"| node_nlu_node
node_nlu_node -->|"parses with"| node_mock_parser
node_nlu_node -.->|"parses with"| node_local_parser
node_local_parser -.->|"uses model"| node_lora_model
node_mock_parser -->|"returns intent"| node_intent
node_local_parser -.->|"returns intent"| node_intent
node_ml_data -->|"trains model"| node_lora_model
node_nlu_node -->|"publishes intent"| node_orchestrator
node_orchestrator -->|"scores skills"| node_affordance_node
node_affordance_node -->|"evaluates usefulness"| node_usefulness
node_affordance_node -->|"evaluates feasibility"| node_feasibility
node_affordance_node -->|"fuses scores"| node_fusion
node_affordance_node -->|"returns rankings"| node_orchestrator
node_orchestrator -->|"builds plan"| node_planner
node_planner -->|"reads skills"| node_skill_registry
node_perception -->|"provides state"| node_feasibility
node_orchestrator -->|"transitions state"| node_state_machine
node_orchestrator -.->|"dispatches skills"| node_skills
node_skills -->|"inherits server"| node_base_skill
node_skills -->|"requests motion"| node_moveit
node_moveit -->|"executes trajectory"| node_controllers
node_controllers -->|"drives joints"| node_robot
node_gazebo -.->|"simulates hardware"| node_controllers
node_isaac -.->|"bridges simulation"| node_robot

click node_nlu_node "https://github.com/armaan-dot/nora/blob/main/ros2_ws/src/nora_nlu_node/nora_nlu_node/nlu_node.py"
click node_mock_parser "https://github.com/armaan-dot/nora/blob/main/ros2_ws/src/nora_nlu_node/nora_nlu_node/mock_parser.py"
click node_local_parser "https://github.com/armaan-dot/nora/blob/main/ros2_ws/src/nora_nlu_node/nora_nlu_node/local_parser.py"
click node_intent "https://github.com/armaan-dot/nora/blob/main/core/nora_core/intent.py"
click node_ml_data "https://github.com/armaan-dot/nora/blob/main/ml/src/nora_nlu/data/synthetic_generator.py"
click node_lora_model "https://github.com/armaan-dot/nora/blob/main/ml/src/nora_nlu/models/lora_model.py"
click node_affordance_node "https://github.com/armaan-dot/nora/tree/main/ros2_ws/src/nora_affordance"
click node_usefulness "https://github.com/armaan-dot/nora/blob/main/ros2_ws/src/nora_affordance/nora_affordance/scorers/llm_usefulness.py"
click node_feasibility "https://github.com/armaan-dot/nora/tree/main/ros2_ws/src/nora_affordance/nora_affordance/scorers"
click node_fusion "https://github.com/armaan-dot/nora/blob/main/core/nora_core/affordance/fusion.py"
click node_planner "https://github.com/armaan-dot/nora/blob/main/core/nora_core/planner.py"
click node_skill_registry "https://github.com/armaan-dot/nora/blob/main/core/nora_core/skills.py"
click node_orchestrator "https://github.com/armaan-dot/nora/blob/main/ros2_ws/src/nora_orchestrator/nora_orchestrator/orchestrator_node.py"
click node_state_machine "https://github.com/armaan-dot/nora/blob/main/ros2_ws/src/nora_orchestrator/nora_orchestrator/state_machine.py"
click node_perception "https://github.com/armaan-dot/nora/tree/main/ros2_ws/src/nora_perception"
click node_skills "https://github.com/armaan-dot/nora/tree/main/ros2_ws/src/nora_skills/nora_skills"
click node_base_skill "https://github.com/armaan-dot/nora/blob/main/ros2_ws/src/nora_skills/nora_skills/base_skill.py"
click node_moveit "https://github.com/armaan-dot/nora/blob/main/ros2_ws/src/nora_moveit_config/launch/move_group.launch.py"
click node_controllers "https://github.com/armaan-dot/nora/blob/main/ros2_ws/src/nora_control/launch/controllers.launch.py"
click node_gazebo "https://github.com/armaan-dot/nora/blob/main/ros2_ws/src/nora_gazebo/launch/gazebo.launch.py"
click node_isaac "https://github.com/armaan-dot/nora/blob/main/ros2_ws/src/nora_isaac/scripts/isaac_bridge_stub.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_nlu_node,node_mock_parser,node_local_parser,node_intent,node_ml_data,node_lora_model toneBlue
class node_affordance_node,node_usefulness,node_feasibility,node_fusion,node_planner,node_skill_registry toneAmber
class node_orchestrator,node_state_machine,node_perception toneMint
class node_skills,node_base_skill,node_moveit,node_controllers,node_robot toneRose
class node_gazebo,node_isaac,node_human toneIndigo
```

## Components

### Language Understanding

- [NLU Node](https://github.com/armaan-dot/nora/blob/main/ros2_ws/src/nora_nlu_node/nora_nlu_node/nlu_node.py): `ros2_ws/src/nora_nlu_node/nora_nlu_node/nlu_node.py`
- [Mock Parser](https://github.com/armaan-dot/nora/blob/main/ros2_ws/src/nora_nlu_node/nora_nlu_node/mock_parser.py): `ros2_ws/src/nora_nlu_node/nora_nlu_node/mock_parser.py`
- [Local Parser](https://github.com/armaan-dot/nora/blob/main/ros2_ws/src/nora_nlu_node/nora_nlu_node/local_parser.py): `ros2_ws/src/nora_nlu_node/nora_nlu_node/local_parser.py`
- [Structured Intent](https://github.com/armaan-dot/nora/blob/main/core/nora_core/intent.py): `core/nora_core/intent.py`
- [NLU Data Pipeline](https://github.com/armaan-dot/nora/blob/main/ml/src/nora_nlu/data/synthetic_generator.py): `ml/src/nora_nlu/data/synthetic_generator.py`
- [LoRA Model](https://github.com/armaan-dot/nora/blob/main/ml/src/nora_nlu/models/lora_model.py): `ml/src/nora_nlu/models/lora_model.py`

### Planning and Scoring

- [Affordance Service](https://github.com/armaan-dot/nora/tree/main/ros2_ws/src/nora_affordance): `ros2_ws/src/nora_affordance`
- [Usefulness Scorer](https://github.com/armaan-dot/nora/blob/main/ros2_ws/src/nora_affordance/nora_affordance/scorers/llm_usefulness.py): `ros2_ws/src/nora_affordance/nora_affordance/scorers/llm_usefulness.py`
- [Feasibility Scorers](https://github.com/armaan-dot/nora/tree/main/ros2_ws/src/nora_affordance/nora_affordance/scorers): `ros2_ws/src/nora_affordance/nora_affordance/scorers`
- [Score Fusion](https://github.com/armaan-dot/nora/blob/main/core/nora_core/affordance/fusion.py): `core/nora_core/affordance/fusion.py`
- [Skill Planner](https://github.com/armaan-dot/nora/blob/main/core/nora_core/planner.py): `core/nora_core/planner.py`
- [Skill Registry](https://github.com/armaan-dot/nora/blob/main/core/nora_core/skills.py): `core/nora_core/skills.py`

### ROS Orchestration

- [Orchestrator Node](https://github.com/armaan-dot/nora/blob/main/ros2_ws/src/nora_orchestrator/nora_orchestrator/orchestrator_node.py): `ros2_ws/src/nora_orchestrator/nora_orchestrator/orchestrator_node.py`
- [Task State Machine](https://github.com/armaan-dot/nora/blob/main/ros2_ws/src/nora_orchestrator/nora_orchestrator/state_machine.py): `ros2_ws/src/nora_orchestrator/nora_orchestrator/state_machine.py`
- [Object Perception](https://github.com/armaan-dot/nora/tree/main/ros2_ws/src/nora_perception): `ros2_ws/src/nora_perception`

### Robot Execution

- [Primitive Skills](https://github.com/armaan-dot/nora/tree/main/ros2_ws/src/nora_skills/nora_skills): `ros2_ws/src/nora_skills/nora_skills`
- [Skill Action Base](https://github.com/armaan-dot/nora/blob/main/ros2_ws/src/nora_skills/nora_skills/base_skill.py): `ros2_ws/src/nora_skills/nora_skills/base_skill.py`
- [MoveIt 2](https://github.com/armaan-dot/nora/blob/main/ros2_ws/src/nora_moveit_config/launch/move_group.launch.py): `ros2_ws/src/nora_moveit_config/launch/move_group.launch.py`
- [ROS Controllers](https://github.com/armaan-dot/nora/blob/main/ros2_ws/src/nora_control/launch/controllers.launch.py): `ros2_ws/src/nora_control/launch/controllers.launch.py`
- **Robot Arm**

### Simulation Targets

- [Gazebo Simulation](https://github.com/armaan-dot/nora/blob/main/ros2_ws/src/nora_gazebo/launch/gazebo.launch.py): `ros2_ws/src/nora_gazebo/launch/gazebo.launch.py`
- [Isaac Simulation](https://github.com/armaan-dot/nora/blob/main/ros2_ws/src/nora_isaac/scripts/isaac_bridge_stub.py): `ros2_ws/src/nora_isaac/scripts/isaac_bridge_stub.py`

### Other components

- **Human Operator**

## Connections

- Human Operator → NLU Node: sends text
- NLU Node → Mock Parser: parses with
- NLU Node → Local Parser: parses with
- Local Parser → LoRA Model: uses model
- Mock Parser → Structured Intent: returns intent
- Local Parser → Structured Intent: returns intent
- NLU Data Pipeline → LoRA Model: trains model
- NLU Node → Orchestrator Node: publishes intent
- Orchestrator Node → Affordance Service: scores skills
- Affordance Service → Usefulness Scorer: evaluates usefulness
- Affordance Service → Feasibility Scorers: evaluates feasibility
- Affordance Service → Score Fusion: fuses scores
- Affordance Service → Orchestrator Node: returns rankings
- Orchestrator Node → Skill Planner: builds plan
- Skill Planner → Skill Registry: reads skills
- Object Perception → Feasibility Scorers: provides state
- Orchestrator Node → Task State Machine: transitions state
- Orchestrator Node → Primitive Skills: dispatches skills
- Primitive Skills → Skill Action Base: inherits server
- Primitive Skills → MoveIt 2: requests motion
- MoveIt 2 → ROS Controllers: executes trajectory
- ROS Controllers → Robot Arm: drives joints
- Gazebo Simulation → ROS Controllers: simulates hardware
- Isaac Simulation → Robot Arm: bridges simulation
