# xuanmai1812/netfabric architecture

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

- Interactive diagram: https://gitdiagram.com/xuanmai1812/netfabric
- Repository: https://github.com/xuanmai1812/netfabric

## Overview

NetFabric is an AWS networking lab whose main workflow is to provision two regional VPCs, manually configure a WireGuard link through SSM, and run cross-network connectivity and throughput checks. The graph includes the documented infrastructure modules and testing/reporting branches; Terraform module wiring and the throughput implementation were not sampled, so those links are shown only where the README supports them.

Main entry points: [`terraform/envs/hub/main.tf`](https://github.com/xuanmai1812/netfabric/blob/main/terraform/envs/hub/main.tf) (Hub environment), [`terraform/envs/spoke/main.tf`](https://github.com/xuanmai1812/netfabric/blob/main/terraform/envs/spoke/main.tf) (Spoke environment), [`terraform/modules/nat-instance/main.tf`](https://github.com/xuanmai1812/netfabric/blob/main/terraform/modules/nat-instance/main.tf) (NAT instances), [`terraform/modules/nat-instance`](https://github.com/xuanmai1812/netfabric/tree/main/terraform/modules/nat-instance) (WireGuard tunnel)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_infra["Network infrastructure"]
  node_hub["Hub environment<br/>[main.tf]"]
  node_spoke["Spoke environment<br/>[main.tf]"]
  node_vpc["VPC networking<br/>[main.tf]"]
  node_testhost["Test hosts<br/>[main.tf]"]
end

subgraph group_access["Tunnel and access"]
  node_iam["SSM IAM role<br/>[main.tf]"]
  node_nat["NAT instances<br/>[main.tf]"]
  node_natboot["NAT boot setup<br/>[user-data.sh]"]
  node_ssm{{"AWS Systems Manager"}}
  node_wireguard["WireGuard tunnel"]
end

subgraph group_validation["Network validation"]
  node_targetgen["Target generation<br/>[get_targets.py]"]
  node_targets["Target inventory<br/>[get_targets.py]"]
  node_matrix["Connectivity checks"]
  node_throughput["Throughput checks<br/>[throughput_test.py]"]
  node_matrixreport["Connectivity report"]
  node_throughputreport["Throughput report<br/>[throughput.json]"]
end

node_operator(("Engineer"))

node_operator -->|"applies Terraform"| node_hub
node_operator -->|"applies Terraform"| node_spoke
node_hub -.->|"provisions network"| node_vpc
node_spoke -.->|"provisions network"| node_vpc
node_hub -.->|"provisions instance"| node_nat
node_spoke -.->|"provisions instance"| node_nat
node_hub -.->|"provisions host"| node_testhost
node_spoke -.->|"provisions host"| node_testhost
node_hub -.->|"assigns SSM role"| node_iam
node_spoke -.->|"assigns SSM role"| node_iam
node_nat -.->|"runs at boot"| node_natboot
node_operator -->|"starts sessions"| node_ssm
node_ssm -->|"administers instances"| node_nat
node_operator -->|"configures manually"| node_wireguard
node_nat -->|"hosts endpoint"| node_wireguard
node_hub -->|"provides outputs"| node_targetgen
node_spoke -->|"provides outputs"| node_targetgen
node_targetgen -->|"writes inventory"| node_targets
node_targets -->|"supplies test targets"| node_matrix
node_matrix -->|"runs remote checks"| node_ssm
node_matrix -->|"writes results"| node_matrixreport
node_throughput -->|"runs remote test"| node_ssm
node_throughput -->|"writes results"| node_throughputreport
node_hub -->|"routes tunnel traffic"| node_wireguard
node_spoke -->|"routes tunnel traffic"| node_wireguard

click node_hub "https://github.com/xuanmai1812/netfabric/blob/main/terraform/envs/hub/main.tf"
click node_spoke "https://github.com/xuanmai1812/netfabric/blob/main/terraform/envs/spoke/main.tf"
click node_vpc "https://github.com/xuanmai1812/netfabric/blob/main/terraform/modules/vpc/main.tf"
click node_iam "https://github.com/xuanmai1812/netfabric/blob/main/terraform/modules/iam/main.tf"
click node_nat "https://github.com/xuanmai1812/netfabric/blob/main/terraform/modules/nat-instance/main.tf"
click node_natboot "https://github.com/xuanmai1812/netfabric/blob/main/terraform/modules/nat-instance/user-data.sh"
click node_testhost "https://github.com/xuanmai1812/netfabric/blob/main/terraform/modules/test-host/main.tf"
click node_wireguard "https://github.com/xuanmai1812/netfabric/tree/main/terraform/modules/nat-instance"
click node_targetgen "https://github.com/xuanmai1812/netfabric/blob/main/tools/get_targets.py"
click node_targets "https://github.com/xuanmai1812/netfabric/blob/main/tools/get_targets.py"
click node_matrix "https://github.com/xuanmai1812/netfabric/blob/main/tools/connectivity_matrix.py"
click node_throughput "https://github.com/xuanmai1812/netfabric/blob/main/tools/throughput_test.py"
click node_matrixreport "https://github.com/xuanmai1812/netfabric/blob/main/reports/connectivity_matrix.json"
click node_throughputreport "https://github.com/xuanmai1812/netfabric/blob/main/reports/throughput.json"

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_hub,node_spoke,node_vpc,node_testhost toneBlue
class node_iam,node_nat,node_natboot,node_ssm,node_wireguard toneAmber
class node_targetgen,node_targets,node_matrix,node_throughput,node_matrixreport,node_throughputreport toneMint
class node_operator toneIndigo
```

## Components

### Network infrastructure

- [Hub environment](https://github.com/xuanmai1812/netfabric/blob/main/terraform/envs/hub/main.tf): `terraform/envs/hub/main.tf`
- [Spoke environment](https://github.com/xuanmai1812/netfabric/blob/main/terraform/envs/spoke/main.tf): `terraform/envs/spoke/main.tf`
- [VPC networking](https://github.com/xuanmai1812/netfabric/blob/main/terraform/modules/vpc/main.tf): `terraform/modules/vpc/main.tf`
- [Test hosts](https://github.com/xuanmai1812/netfabric/blob/main/terraform/modules/test-host/main.tf): `terraform/modules/test-host/main.tf`

### Tunnel and access

- [SSM IAM role](https://github.com/xuanmai1812/netfabric/blob/main/terraform/modules/iam/main.tf): `terraform/modules/iam/main.tf`
- [NAT instances](https://github.com/xuanmai1812/netfabric/blob/main/terraform/modules/nat-instance/main.tf): `terraform/modules/nat-instance/main.tf`
- [NAT boot setup](https://github.com/xuanmai1812/netfabric/blob/main/terraform/modules/nat-instance/user-data.sh): `terraform/modules/nat-instance/user-data.sh`
- **AWS Systems Manager**
- [WireGuard tunnel](https://github.com/xuanmai1812/netfabric/tree/main/terraform/modules/nat-instance): `terraform/modules/nat-instance`

### Network validation

- [Target generation](https://github.com/xuanmai1812/netfabric/blob/main/tools/get_targets.py): `tools/get_targets.py`
- [Target inventory](https://github.com/xuanmai1812/netfabric/blob/main/tools/get_targets.py): `tools/get_targets.py`
- [Connectivity checks](https://github.com/xuanmai1812/netfabric/blob/main/tools/connectivity_matrix.py): `tools/connectivity_matrix.py`
- [Throughput checks](https://github.com/xuanmai1812/netfabric/blob/main/tools/throughput_test.py): `tools/throughput_test.py`
- [Connectivity report](https://github.com/xuanmai1812/netfabric/blob/main/reports/connectivity_matrix.json): `reports/connectivity_matrix.json`
- [Throughput report](https://github.com/xuanmai1812/netfabric/blob/main/reports/throughput.json): `reports/throughput.json`

### Other components

- **Engineer**

## Connections

- Engineer → Hub environment: applies Terraform (evidence: `README.md`)
- Engineer → Spoke environment: applies Terraform (evidence: `README.md`)
- Hub environment → VPC networking: provisions network
- Spoke environment → VPC networking: provisions network
- Hub environment → NAT instances: provisions instance
- Spoke environment → NAT instances: provisions instance
- Hub environment → Test hosts: provisions host
- Spoke environment → Test hosts: provisions host
- Hub environment → SSM IAM role: assigns SSM role
- Spoke environment → SSM IAM role: assigns SSM role
- NAT instances → NAT boot setup: runs at boot
- Engineer → AWS Systems Manager: starts sessions (evidence: `README.md`)
- AWS Systems Manager → NAT instances: administers instances (evidence: `README.md`)
- Engineer → WireGuard tunnel: configures manually (evidence: `README.md`)
- NAT instances → WireGuard tunnel: hosts endpoint (evidence: `README.md`)
- Hub environment → Target generation: provides outputs (evidence: `README.md`)
- Spoke environment → Target generation: provides outputs (evidence: `README.md`)
- Target generation → Target inventory: writes inventory (evidence: `tools/get_targets.py`)
- Target inventory → Connectivity checks: supplies test targets (evidence: `tools/connectivity_matrix.py`)
- Connectivity checks → AWS Systems Manager: runs remote checks (evidence: `tools/connectivity_matrix.py`)
- Connectivity checks → Connectivity report: writes results (evidence: `README.md`)
- Throughput checks → AWS Systems Manager: runs remote test (evidence: `README.md`)
- Throughput checks → Throughput report: writes results (evidence: `README.md`)
- Hub environment → WireGuard tunnel: routes tunnel traffic (evidence: `README.md`)
- Spoke environment → WireGuard tunnel: routes tunnel traffic (evidence: `README.md`)
