[#11] feat: Establish discovery system and add support for /areas

docs/README.md

@@ -0,0 +1,31 @@
+# ROS 2 Medkit Gateway - Architecture Documentation
+
+This directory contains design documentation for the ros2_medkit_gateway project.
+
+## Architecture Diagram
+
+The `architecture.puml` file contains a PlantUML class diagram showing the relationships between the main components of the gateway.
+
+### Main Components
+
+1. **GatewayNode** - The main ROS 2 node that orchestrates the system
+   - Extends `rclcpp::Node`
+   - Manages periodic discovery and cache refresh
+   - Runs the REST server in a separate thread
+   - Provides thread-safe access to the entity cache
+
+2. **DiscoveryManager** - Discovers ROS 2 entities and maps them to the SOVD hierarchy
+   - Discovers Areas from node namespaces
+   - Discovers Components from nodes, topics, and services
+   - Extracts the entity hierarchy from the ROS 2 graph
+
+3. **RESTServer** - Provides the HTTP/REST API
+   - Serves endpoints: `/health`, `/`, `/areas`
+   - Retrieves cached entities from the GatewayNode
+   - Runs on configurable host and port
+
+4. **Data Models** - Entity representations
+   - `Area` - Physical or logical domain
+   - `Component` - Hardware or software component
+   - `EntityCache` - Thread-safe cache of discovered entities
+

docs/architecture.puml

@@ -0,0 +1,92 @@
+@startuml ros2_medkit_gateway_architecture
+
+!theme plain
+skinparam linetype ortho
+skinparam classAttributeIconSize 0
+
+title ROS 2 Medkit Gateway - Class Architecture
+
+package "ROS 2 Framework" {
+    class rclcpp::Node {
+        +get_node_names()
+        +get_topic_names_and_types()
+        +get_service_names_and_types()
+    }
+}
+
+package "ros2_medkit_gateway" {
+
+    class GatewayNode {
+        + get_entity_cache(): EntityCache
+    }
+
+    class DiscoveryManager {
+        + discover_areas(): vector<Area>
+        + discover_components(): vector<Component>
+    }
+
+    class RESTServer {
+        + start(): void
+        + stop(): void
+    }
+
+    class Area {
+        + id: string
+        + namespace_path: string
+        + type: string
+        + to_json(): json
+    }
+
+    class Component {
+        + id: string
+        + namespace_path: string
+        + fqn: string
+        + type: string
+        + area: string
+        + to_json(): json
+    }
+
+    class EntityCache {
+        + areas: vector<Area>
+        + components: vector<Component>
+        + last_update: time_point
+    }
+}
+
+package "External Libraries" {
+    class "httplib::Server" as HTTPLibServer
+    class "nlohmann::json" as JSON
+}
+
+' Relationships
+
+' Inheritance
+GatewayNode -up-|> rclcpp::Node : extends
+
+' Composition (Gateway owns these)
+GatewayNode *-down-> DiscoveryManager : owns
+GatewayNode *-down-> RESTServer : owns
+GatewayNode *-down-> EntityCache : owns
+
+' Discovery Manager uses Node interface
+DiscoveryManager --> rclcpp::Node : uses
+
+' REST Server references Gateway
+RESTServer --> GatewayNode : uses
+
+' Entity Cache aggregates entities
+EntityCache o-right-> Area : contains many
+EntityCache o-right-> Component : contains many
+
+' Discovery produces entities
+DiscoveryManager ..> Area : creates
+DiscoveryManager ..> Component : creates
+
+' REST Server uses HTTP library
+RESTServer *--> HTTPLibServer : owns
+
+' Models use JSON for serialization
+Area ..> JSON : serializes to
+Component ..> JSON : serializes to
+
+@enduml

postman/README.md

@@ -0,0 +1,61 @@
+# ROS 2 Medkit Gateway Postman Collection
+
+This folder contains Postman collections for testing the ROS 2 Medkit Gateway REST API.
+
+## Current Collection:
+
+**Collection:** `ros2-medkit-gateway.postman_collection.json`
+
+Includes below endpoints:
+- ✅ GET `/` - Gateway info
+- ✅ GET `/areas` - List all areas
+
+## Quick Start
+
+### 1. Import Collection
+
+**In Postman Desktop:**
+1. Click **Import** button (top-left)
+2. Select: `postman/collections/ros2-medkit-gateway.postman_collection.json`
+3. Click **Import**
+
+### 2. Import Environment
+
+1. Click **Environments** icon (left sidebar)
+2. Click **Import**
+3. Select: `postman/environments/local.postman_environment.json`
+4. Activate environment: Select **"ROS 2 Medkit Gateway - Local"** from dropdown (top-right)
+
+### 3. Start Gateway & Demo Nodes
+
+**Terminal 1 - Gateway:**
+```bash
+ros2 launch ros2_medkit_gateway gateway.launch.py
+```
+
+**Terminal 2 - Demo Nodes:**
+```bash
+ros2 launch ros2_medkit_gateway demo_nodes.launch.py
+```
+
+### 4. Test
+
+1. In Postman, expand **"Discovery"** folder
+2. Click **"GET Gateway Info"**
+3. Click **Send**
+4. You should see: `{"status": "ROS 2 Medkit Gateway running", "version": "0.1.0", ...}`
+
+5. Click **"GET List Areas"**
+6. Click **Send**
+7. You should see areas: `[{"id": "powertrain", ...}, {"id": "chassis", ...}, ...]`
+
+## API Variables
+
+The environment includes:
+- `base_url`: `http://localhost:8080` (default gateway address)
+
+You can change the port if your gateway runs on a different port.
+
+---
+
+**Happy Testing! 🚀**

postman/collections/ros2-medkit-gateway.postman_collection.json

@@ -0,0 +1,50 @@
+{
+  "info": {
+    "name": "ROS 2 Medkit Gateway API",
+    "description": "Minimal collection: GET / and GET /areas endpoints only",
+    "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json"
+  },
+  "item": [
+    {
+      "name": "Discovery",
+      "item": [
+        {
+          "name": "GET Gateway Info",
+          "request": {
+            "method": "GET",
+            "header": [],
+            "url": {
+              "raw": "{{base_url}}/",
+              "host": [
+                "{{base_url}}"
+              ],
+              "path": [
+                ""
+              ]
+            },
+            "description": "Get gateway status and version information"
+          },
+          "response": []
+        },
+        {
+          "name": "GET List Areas",
+          "request": {
+            "method": "GET",
+            "header": [],
+            "url": {
+              "raw": "{{base_url}}/areas",
+              "host": [
+                "{{base_url}}"
+              ],
+              "path": [
+                "areas"
+              ]
+            },
+            "description": "List all discovered areas (powertrain, chassis, body, root)"
+          },
+          "response": []
+        }
+      ]
+    }
+  ]
+}

postman/environments/local.postman_environment.json

@@ -0,0 +1,11 @@
+{
+  "name": "ROS 2 Medkit Gateway - Local",
+  "values": [
+    {
+      "key": "base_url",
+      "value": "http://localhost:8080",
+      "type": "default",
+      "enabled": true
+    }
+  ]
+}