# karimelmasry42/ns3-rba-vanet-reproducibility architecture

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

- Interactive diagram: https://gitdiagram.com/karimelmasry42/ns3-rba-vanet-reproducibility
- Repository: https://github.com/karimelmasry42/ns3-rba-vanet-reproducibility

## Overview

#### Purpose and Integration Model
This is an overlay for a pinned `ns-3-dev` revision, not a standalone application. It reproduces VANET scaling measurements for proof-bearing vehicle-to-RSU authentication over IEEE 802.11p. The overlay is copied into an ns-3 tree; no `src/` changes are required. Primary experiment source: `scratch/rba-paper-scaling.cc`. Build integration depends on `scratch/CMakeLists.txt` (referenced by the README but absent from the supplied tree).

#### Entry Points
- Simulation executable: the ns-3 scratch target built from `scratch/rba-paper-scaling.cc`; accepts topology, timing, beacon interval, and CSV-output arguments.
- Sweep orchestrator: `tools/rba/run-scaling.sh`; builds if needed, selects vehicle-count schedules, repeats runs, and coordinates aggregation/plotting.
- Analysis/visualization: `tools/rba/plot-scaling.py`; consumes run-level CSV data to produce grouped node-count summaries and SVG figures.

#### Simulation Topology and Wireless Boundary
`scratch/rba-paper-scaling.cc` creates only wireless vehicle OBUs and RSUs. Vehicles move on a multi-lane highway, choose the nearest RSU from initial position, and retain that association. Communications use 802.11p ad hoc networking, fixed communication range, and an OFDM 6 Mbps/10 MHz PHY mode. The modeled network boundary is a single vehicle-prover → RSU-verifier wireless hop.

#### Authentication Workload Mapping
The simulation represents each vehicle transmission as a fixed-size authenticated payload containing pseudonym identifiers, a compressed Sigma-style ZK proof, timestamp, and signature. Vehicle-side proof/signing and RSU-side verification/eligibility work are modeled as fixed processing-delay constants rather than executable cryptography. Logical TA, pseudonym list, RSU key ledger, blockchain, consensus, and feedback/reputation-update paths are explicitly outside ns-3 node and airtime modeling.

Relevant implementation path: `scratch/rba-paper-scaling.cc`.

#### Measurement and Result Semantics
FlowMonitor-derived packet counts and one-way wireless delay drive per-run metrics. Packet loss is computed from transmitted versus received packets; reported RBA end-to-end delay adds fixed prover and verifier processing delays to measured network delay. The simulator appends one row per run to a configured CSV; the result schema also captures topology, radio/payload settings, timing windows, offered load, and wall-clock duration.

Committed example artifacts establish expected output contracts:
- `results/rba/rba-scaling-summary.csv`
- `results/rba/rba-node-count-summary.csv`

#### Sweep, Aggregation, and Plot Pipeline
`tools/rba/run-scaling.sh` is the control-plane pipeline: it resolves explicit, uniform, or segmented vehicle-count schedules; executes repeated seeded simulations; manages FlowMonitor XML retention; and writes/merges run data. It then invokes `tools/rba/plot-scaling.py` to group observations by vehicle count, calculate descriptive statistics, and render packet-loss and authenticated-delay scaling figures. Plot artifacts are generated outputs, not simulation inputs.

#### Runtime and External Dependencies
The material runtime is C++ on ns-3-dev at the documented pinned commit, configured and built with CMake. Batch execution requires a POSIX shell; post-processing requires Python and its plotting/data dependencies as used by `tools/rba/plot-scaling.py`. There are no live TA, blockchain, cloud, database, or web-service dependencies: those roles are abstract protocol context only.

Main entry points: [`scratch/rba-paper-scaling.cc`](https://github.com/karimelmasry42/ns3-rba-vanet-reproducibility/blob/main/scratch/rba-paper-scaling.cc) (RBA scaling simulation), [`tools/rba/plot-scaling.py`](https://github.com/karimelmasry42/ns3-rba-vanet-reproducibility/blob/main/tools/rba/plot-scaling.py) (Scaling analysis and plots), [`tools/rba/run-scaling.sh`](https://github.com/karimelmasry42/ns3-rba-vanet-reproducibility/blob/main/tools/rba/run-scaling.sh) (Scaling sweep runner), [`results/rba/rba-scaling-summary.csv`](https://github.com/karimelmasry42/ns3-rba-vanet-reproducibility/blob/main/results/rba/rba-scaling-summary.csv) (Scaling summary CSV)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ns3["ns-3 simulation"]
  node_ns3dev["Pinned ns-3-dev<br/>simulation runtime"]
  node_sim["RBA scaling simulation<br/>C++ scratch target"]
  node_vehicles(("Vehicle OBUs<br/>wireless prover nodes"))
  node_rsus(("RSUs<br/>wireless verifier nodes"))
  node_wireless["802.11p ad hoc hop<br/>wireless boundary"]
  node_authworkload["Authenticated payload workload<br/>protocol model"]
  node_processing["Fixed auth processing delays<br/>timing model"]
  node_metrics["FlowMonitor metrics<br/>measurement layer"]
  node_scratchcmake["Scratch target registration<br/>CMake integration"]
end

subgraph group_pipeline["Sweep and analysis"]
  node_runner["Scaling sweep runner<br/>POSIX shell orchestrator<br/>[run-scaling.sh]"]
  node_plotter["Scaling analysis and plots<br/>Python post-processor<br/>[plot-scaling.py]"]
end

subgraph group_outputs["Results"]
  node_runscsv[("Run-level CSV<br/>measurement data")]
  node_summary["Scaling summary CSV<br/>committed result artifact"]
  node_nodesummary["Node-count summary CSV<br/>committed result artifact"]
  node_figures["Scaling SVG figures<br/>generated visualization"]
end

node_ns3dev -->|"configures"| node_scratchcmake
node_scratchcmake -->|"builds target"| node_sim
node_runner -->|"builds if needed"| node_ns3dev
node_runner -->|"executes repeated runs"| node_sim
node_vehicles -->|"prover transmissions"| node_wireless
node_wireless -->|"single-hop delivery"| node_rsus
node_authworkload -->|"models transmitted payload"| node_vehicles
node_authworkload -->|"maps crypto to delays"| node_processing
node_processing -->|"models verification work"| node_rsus
node_sim -->|"creates and moves"| node_vehicles
node_sim -->|"creates and associates"| node_rsus
node_sim -->|"collects flow data"| node_metrics
node_metrics -->|"appends per-run row"| node_runscsv
node_runner -->|"writes and merges"| node_runscsv
node_runner -->|"invokes"| node_plotter
node_runscsv -->|"consumes observations"| node_plotter
node_plotter -->|"writes summaries"| node_summary
node_plotter -->|"groups by vehicle count"| node_nodesummary
node_plotter -->|"renders"| node_figures

click node_sim "https://github.com/karimelmasry42/ns3-rba-vanet-reproducibility/blob/main/scratch/rba-paper-scaling.cc"
click node_vehicles "https://github.com/karimelmasry42/ns3-rba-vanet-reproducibility/blob/main/scratch/rba-paper-scaling.cc"
click node_rsus "https://github.com/karimelmasry42/ns3-rba-vanet-reproducibility/blob/main/scratch/rba-paper-scaling.cc"
click node_wireless "https://github.com/karimelmasry42/ns3-rba-vanet-reproducibility/blob/main/scratch/rba-paper-scaling.cc"
click node_authworkload "https://github.com/karimelmasry42/ns3-rba-vanet-reproducibility/blob/main/scratch/rba-paper-scaling.cc"
click node_processing "https://github.com/karimelmasry42/ns3-rba-vanet-reproducibility/blob/main/scratch/rba-paper-scaling.cc"
click node_metrics "https://github.com/karimelmasry42/ns3-rba-vanet-reproducibility/blob/main/scratch/rba-paper-scaling.cc"
click node_runner "https://github.com/karimelmasry42/ns3-rba-vanet-reproducibility/blob/main/tools/rba/run-scaling.sh"
click node_plotter "https://github.com/karimelmasry42/ns3-rba-vanet-reproducibility/blob/main/tools/rba/plot-scaling.py"
click node_summary "https://github.com/karimelmasry42/ns3-rba-vanet-reproducibility/blob/main/results/rba/rba-scaling-summary.csv"
click node_nodesummary "https://github.com/karimelmasry42/ns3-rba-vanet-reproducibility/blob/main/results/rba/rba-node-count-summary.csv"

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_ns3dev,node_sim,node_vehicles,node_rsus,node_wireless,node_authworkload,node_processing,node_metrics,node_scratchcmake toneBlue
class node_runner,node_plotter toneAmber
class node_runscsv,node_summary,node_nodesummary,node_figures toneMint
```

## Components

### ns-3 simulation

- **Pinned ns-3-dev**: simulation runtime · Host tree and CMake build environment for the overlay.
- [RBA scaling simulation](https://github.com/karimelmasry42/ns3-rba-vanet-reproducibility/blob/main/scratch/rba-paper-scaling.cc): C++ scratch target · Creates the VANET experiment and appends one CSV row per run. · `scratch/rba-paper-scaling.cc`
- [Vehicle OBUs](https://github.com/karimelmasry42/ns3-rba-vanet-reproducibility/blob/main/scratch/rba-paper-scaling.cc): wireless prover nodes · Mobile highway nodes retain their initially nearest RSU association. · `scratch/rba-paper-scaling.cc`
- [RSUs](https://github.com/karimelmasry42/ns3-rba-vanet-reproducibility/blob/main/scratch/rba-paper-scaling.cc): wireless verifier nodes · Static verifier nodes perform modeled eligibility and verification work. · `scratch/rba-paper-scaling.cc`
- [802.11p ad hoc hop](https://github.com/karimelmasry42/ns3-rba-vanet-reproducibility/blob/main/scratch/rba-paper-scaling.cc): wireless boundary · Fixed-range 6 Mbps/10 MHz OFDM vehicle-to-RSU communication. · `scratch/rba-paper-scaling.cc`
- [Authenticated payload workload](https://github.com/karimelmasry42/ns3-rba-vanet-reproducibility/blob/main/scratch/rba-paper-scaling.cc): protocol model · Fixed payload contains pseudonym, compressed ZK proof, timestamp, and signature. · `scratch/rba-paper-scaling.cc`
- [Fixed auth processing delays](https://github.com/karimelmasry42/ns3-rba-vanet-reproducibility/blob/main/scratch/rba-paper-scaling.cc): timing model · Prover signing and verifier processing replace executable cryptography. · `scratch/rba-paper-scaling.cc`
- [FlowMonitor metrics](https://github.com/karimelmasry42/ns3-rba-vanet-reproducibility/blob/main/scratch/rba-paper-scaling.cc): measurement layer · Derives packet counts, wireless delay, loss, and RBA end-to-end delay. · `scratch/rba-paper-scaling.cc`
- **Scratch target registration**: CMake integration · Required scratch build registration referenced by the README.

### Sweep and analysis

- [Scaling sweep runner](https://github.com/karimelmasry42/ns3-rba-vanet-reproducibility/blob/main/tools/rba/run-scaling.sh): POSIX shell orchestrator · Builds, schedules vehicle counts, repeats seeded runs, and manages FlowMonitor XML. · `tools/rba/run-scaling.sh`
- [Scaling analysis and plots](https://github.com/karimelmasry42/ns3-rba-vanet-reproducibility/blob/main/tools/rba/plot-scaling.py): Python post-processor · Groups observations, calculates statistics, and renders SVG figures. · `tools/rba/plot-scaling.py`

### Results

- **Run-level CSV**: measurement data · Per-run metrics plus topology, radio, timing, load, and duration fields.
- [Scaling summary CSV](https://github.com/karimelmasry42/ns3-rba-vanet-reproducibility/blob/main/results/rba/rba-scaling-summary.csv): committed result artifact · `results/rba/rba-scaling-summary.csv`
- [Node-count summary CSV](https://github.com/karimelmasry42/ns3-rba-vanet-reproducibility/blob/main/results/rba/rba-node-count-summary.csv): committed result artifact · `results/rba/rba-node-count-summary.csv`
- **Scaling SVG figures**: generated visualization · Packet-loss and authenticated-delay scaling plots.

## Connections

- Pinned ns-3-dev → Scratch target registration: configures
- Scratch target registration → RBA scaling simulation: builds target
- Scaling sweep runner → Pinned ns-3-dev: builds if needed
- Scaling sweep runner → RBA scaling simulation: executes repeated runs
- Vehicle OBUs → 802.11p ad hoc hop: prover transmissions
- 802.11p ad hoc hop → RSUs: single-hop delivery
- Authenticated payload workload → Vehicle OBUs: models transmitted payload
- Authenticated payload workload → Fixed auth processing delays: maps crypto to delays
- Fixed auth processing delays → RSUs: models verification work
- RBA scaling simulation → Vehicle OBUs: creates and moves
- RBA scaling simulation → RSUs: creates and associates
- RBA scaling simulation → FlowMonitor metrics: collects flow data
- FlowMonitor metrics → Run-level CSV: appends per-run row
- Scaling sweep runner → Run-level CSV: writes and merges
- Scaling sweep runner → Scaling analysis and plots: invokes
- Run-level CSV → Scaling analysis and plots: consumes observations
- Scaling analysis and plots → Scaling summary CSV: writes summaries
- Scaling analysis and plots → Node-count summary CSV: groups by vehicle count
- Scaling analysis and plots → Scaling SVG figures: renders