[DOCS] Restructuring docs for Smart Tolling

Signed-off-by: Sebastian Golebiewski <sebastianx.golebiewski@intel.com>

Author: sgolebiewski-intel

metro-ai-suite/metro-vision-ai-app-recipe/smart-tolling/README.md

@@ -6,36 +6,52 @@ Enabling such use cases across multiple viewpoints helps in understanding the ob
 
 ![Smart Tolling System Architecture](./docs/user-guide/_assets/smart_tolling_architecture.png)
 
-## Use Cases
+## Key Features
 
-- **Vehicle Axle Detection**: Determines vehicle class based on axle and wheel count
-  - Usage: Used for toll classification and revenue calculation.
-- **License Plate Detection**: Identifies vehicles uniquely using license plates
-  - Usage: Used for reading vehicle license plate text from both front and rear views.
-- **Visualization & Analytics**:Provides real-time and historical insights for toll operators.
+**Multi vision**:
 
-## Key Benefits
+Scene-based analytics allow insights beyond single sensor views.
 
-- **Accuracy**: Multi view accuracy.
-- **Revenue Protection**: Advanced "Lift Axle" detection using Computer Vision allows for accurate tariffing.
-- **Audit Compliance**: Every transaction includes an "Image Evidence" for simplified auditing.
+- **Vehicle axle detection**:
+
+  Vehicle class is determined based on axle and wheel count.\
+  Intended for toll classification, as well as revenue calculation and protection.\
+  Multi view and the advanced "lift axle" detection using computer vision
+  ensures accurate tariffing.
+
+- **License plate detection**:
+
+  The application identifies vehicles uniquely by their license plates, which are
+  read from both front and rear views.\
+  The image evidence is included in every transaction for simplified auditing.
+
+**Visualization & analytics**:
+
+Provides real-time and historical insights for toll operators.
+
+**Modularity**:
+
+Architecture based on modular microservices enables composability and reconfiguration.
+
+**High-throughput processing**:
+
+Optimized video pipelines for Intel edge devices.
 
 ## How it Works
 
 The system uses the **Metro Edge Architecture** based on three key principles:
 
-1. **Perception**: Deep Learning Streamer (DLStreamer) processes 3/4 camera feeds.
-2. **Control**: SceneScape Controller aggregates metadata.
-3. **Analytics**: Node-RED transforms events into traffic insights (Traffic Volume, Flow Efficiency, Tariffing).
-
-For more details, refer to [How it Works](./docs/user-guide/how-it-works.md).
+- **Perception**: Deep Learning Streamer (DLStreamer) [processes 3/4 camera feeds](./docs/user-guide/perception-layer.md).
+- **Control**: SceneScape Controller [aggregates metadata](./docs/user-guide/how-it-works.md#analytics-pipeline-downstream).
+- **Analytics**: Node-RED [transforms events into traffic insights](./docs/user-guide/how-it-works.md#node-red-transformation)
+  (Traffic Volume, Flow Efficiency, Tariffing).
 
 ## Learn More
 
-- [System Requirements](./docs/user-guide/get-started/system-requirements.md): Hardware, OS and Software Prerequisites.
-- [Get Started](./docs/user-guide/get-started.md): Installation, Configuration and Launch steps.
-- [Technical Reference](./docs/user-guide/how-it-works/technical-reference.md): Engineering Specs, Zero-Copy Pipeline and API usage.
-- [Troubleshooting](./docs/user-guide/troubleshooting.md): Solutions to common issues.
+- [System Requirements](./docs/user-guide/get-started/system-requirements.md)
+- [Get Started](docs/user-guide/get-started.md)
+- [How It Works](./docs/user-guide/how-it-works.md)
+- [Troubleshooting](./docs/user-guide/troubleshooting.md)
 
 ## License
 

metro-ai-suite/metro-vision-ai-app-recipe/smart-tolling/docs/user-guide/api-reference.md

@@ -0,0 +1,28 @@
+# API Reference
+
+Integrators can subscribe to `scenescape/cmd/camera/#` for real-time events.
+See the sample JSON Payload Schema (v2) below:
+
+```json
+{
+  "id": "toll_side_1",
+  "timestamp": "2026-02-03T12:00:00.000Z",
+  "objects": {
+    "vehicle": [
+      {
+        "id": 1,
+        "vehicle_type": "truck",
+        "confidence": 0.98,
+        "bounding_box_px": { "x": 100, "y": 200, "width": 500, "height": 300 },
+
+        "axle_count": 3,
+        "wheel_count": 6,
+        "wheels_touching_ground": 4,  // 1 Lift Axle detected!
+
+        "vehicle_color": "white",
+        "vehicle_image_b64": "..."    // High-res crop for audit
+      }
+    ]
+  }
+}
+```

metro-ai-suite/metro-vision-ai-app-recipe/smart-tolling/docs/user-guide/how-it-works.md

@@ -1,59 +1,125 @@
 # How It Works
 
-This section provides a high-level view of how the application integrates with a typical system architecture.
+This section provides a high-level view of how the application integrates with a
+typical system architecture.
 
 ![High-Level System Diagram](./_assets/smart_tolling_architecture.png)
 
 ## Diagram Description
 
-- **Inputs**:
+### Inputs
 
-  Video recordings are used to simulate a live feed from cameras deployed at a toll.
-  The application can be configured to work with live cameras.
+Video recordings are used to simulate a live feed from cameras deployed at a toll.
+The application can be configured to work with live cameras.
 
-  - **Video Files** - Tolling cameras that capture videos simultaneously from front,
-    rear and side profiles.
-  - **Scene Database** - Pre-configured intersection scene with satellite view of
-    tolling area, calibrated cameras and regions of interest.
+- **Video Files** - Tolling cameras that capture videos simultaneously from front,
+  rear and side profiles.
+- **Scene Database** - Pre-configured intersection scene with satellite view of
+  tolling area, calibrated cameras and regions of interest.
 
-- **Processing**:
+### Core (Processing)
 
-  - **Video Analytics** - Deep Learning Streamer Pipeline Server
-    (DL Streamer Pipeline Server) utilizes a pre-trained object detection model
-    to generate object detection metadata and and a local NTP server for
-    synchronized timestamps. This metadata is published to the MQTT broker.
-  - **Sensor Fusion** - Scene Controller Microservice fuses the metadata from
-    video analytics utilizing scene data obtained through the Scene Management API.
-    It uses the fused tracks and the configured analytics (regions of interest)
-    to generate events that are published to the MQTT broker.
-  - **Aggregate Scene Analytics** - Region of interests analytics are read from
-    the MQTT broker and stored in an InfluxDB bucket that enables time series analysis through Flux queries.
-- **Outputs**:
-  - Fused object tracks are available on the MQTT broker and visualized through the Scene Management UI.
-  - Aggregated toll analytics are visualized through a Grafana dashboard.
+- [**Video Analytics**](./perception-layer.md) - Deep Learning Streamer Pipeline Server
+  (DL Streamer Pipeline Server) utilizes a pre-trained object detection model
+  to [generate object detection metadata](#zero-copy-video-pipeline) and and a local
+  NTP server for synchronized timestamps. This metadata is published to the MQTT broker.
+- **Sensor Fusion** - Scene Controller Microservice fuses the metadata from
+  video analytics utilizing scene data obtained through the Scene Management API.
+  It uses the fused tracks and the configured analytics (regions of interest)
+  to generate events that are published to the MQTT broker.
+- [**Aggregate Scene Analytics**](#node-red-transformation) - Region of interests
+  analytics are read from the MQTT broker and
+  [stored in an InfluxDB bucket](#storage-influxdb) that enables time series
+  analysis through Flux queries.
 
-## Key Features
+### Live Feed Output
 
-- **Feature 1**: Architecture based on modular microservices enables composability and reconfiguration.
-- **Feature 2**: Optimized video pipelines for Intel edge devices.
-- **Feature 3**: Scene-based analytics allow insights beyond single sensor views.
+- Fused object tracks are available on the MQTT broker and visualized through
+  the Scene Management UI.
+- [Aggregated toll analytics](#analytics-pipeline-downstream) are visualized
+  through a Grafana dashboard.
+
+### Workflow
+
+1. Video loops or RTSP is fed into DL Streamer.
+2. Trained AI models detect vehicles and license plates.
+3. Metadata is published to MQTT.
+4. SceneScape maps detections to scene regions to get exact location of objects on the scene.
+5. Exit events are generated when vehicles leave the region.
+6. Node-RED processes only finalized exit events by subscribing to SceneScape topics.
+7. Data is written to InfluxDB for system to access for consistent information.
+8. Grafana visualizes real time and historical data enabling access to metrics
+   and vehicle details.
+
+## Optimizations
+
+The system achieves high-throughput processing on Edge hardware through specific
+optimizations defined in `config.json`. The [`docker-compose.yml`](./_assets/docker-compose.yml)
+file mentions all the services and the pipelines are configured in `config.json` file.
+
+### Zero-Copy Video Pipeline
+
+Unlike standard OpenCV pipelines that copy frames to CPU RAM, this solution utilizes **VASurface Sharing plugin**.
+
+- **Mechanism:** Decoded video frames remain in GPU memory (`video/x-raw(memory:VAMemory)`).
+- **Benefit:** Zero-copy inference eliminates PCIe bandwidth bottlenecks, reducing end-to-end latency by ~40%.
+- **Config Evidence:** `pre-process-backend=va-surface-sharing` used in all `gvadetect` elements.
+
+### Dynamic ROI Inference (Hierarchical Execution)
+
+To maximize efficiency, heavy neural networks (like Axle Counting) do not run on the full 4K frame.
+
+- **Logic:** The "Vehicle Type" model runs first to find the bounding box.
+- **Optimization:** The Axle model is configured with `inference-region=roi-list`,
+  forcing it to execute *only* within the coordinates of the detected vehicle.
+- **Impact:** Reduces pixel processing load by >80% for sparse traffic scenes.
+
+### Hybrid Workload Distribution
+
+The pipeline intelligently maps models to available accelerators to prevent resource contention:
+
+- **GPU (Flex Series):** Handles heavy convolution tasks (Vehicle Detection, LPR, Axle Counting).
+- **CPU (Xeon):** Handles lighter classification tasks (Vehicle Color) and post-processing adapters (`gvapython`).
+
+## Analytics Pipeline (Downstream)
+
+Raw metadata is valuable, but actionable insights come from the Analytics Pipeline.
+
+## Node-RED Transformation
+
+- **Input:** The **MQTT IN Node** subscribes to `scenescape/event/region/+/+/objects`.
+- **Logic:** The **Function node** aggregates counts per region and calculates **Dwell Time** (congestion).
+- **Output:** The **InfluxDB OUT Node** writes normalized data points to InfluxDB.
+
+![Node-RED Flow](./_assets/smart_tolling_nodered.png)
+
+### Storage (InfluxDB)
+
+InfluxDB acts as a single source of truth. All critical and shared data is
+stored in one location, ensuring every user and system accesses the same,
+accurate and consistent information.
+
+![InfluxDB Dashboard 1](./_assets/smart_tolling_influx_db.png)
+
+### Visualization (Grafana)
+
+The system ships with a pre-configured dashboard (`anthem-intersection.json` schema)
+focusing on Traffic Volume, Flow Efficiency and Safety Alerts.
+
+![Grafana Dashboard 1](./_assets/garfana_Dashboard1.png)
 
 ## Learn More
 
-- [System Requirements](./get-started/system-requirements.md):
-  Check the hardware and software requirements for deploying the application.
-- [Get Started](./get-started.md):
-  Follow step-by-step instructions to set up the application.
-- [Technical Reference](./how-it-works/technical-reference.md): Learn more about engineering specification and
-  how to use Zero-Copy Pipeline and API.
-- [Support and Troubleshooting](./troubleshooting.md):
-  Find solutions to common issues and troubleshooting steps.
+- [System Requirements](./get-started/system-requirements.md)
+- [Get Started](./get-started.md)
+- [API Reference](./api-reference.md)
+- [Support and Troubleshooting](./troubleshooting.md)
 
 <!--hide_directive
 :::{toctree}
 :hidden:
 
-./how-it-works/technical-reference
+./perception-layer
 
 :::
 hide_directive-->