# harvard-cs145/routing architecture

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

- Interactive diagram: https://gitdiagram.com/harvard-cs145/routing
- Repository: https://github.com/harvard-cs145/routing

## Overview

1. **Repository purpose**
   - This is a Python networking project focused on **intra-domain routing**.
   - The only required algorithm implementations are in **`DVrouter.py`** and/or **`LSrouter.py`**.

2. **Core architecture**
   - The repo is built around a **network simulator** that instantiates one router object per router node and connects them with simulated links.
   - The simulator drives each router by calling event handlers such as packet arrival, link add/remove, and timer/heartbeat events.

3. **Main runtime boundary**
   - The simulator treats each router as an independent actor and runs them in **separate threads**.
   - That makes the routing logic decentralized: routers only know their local state plus messages received from neighbors.

4. **Packet and message flow**
   - `packet.py` defines the packet model used both for normal client traffic and for routing control messages.
   - Client packets are used for traceroute-like path verification; routing packets are sent between routers with `kind == Packet.ROUTING` and JSON-string content.
   - A key boundary is that router code may manipulate packet fields, but must not touch the packet route-tracking internals.

5. **Router abstraction**
   - `router.py` provides the base `Router` interface that both algorithm implementations extend.
   - The important overridable hooks are `__init__`, `handle_packet`, `handle_new_link`, `handle_remove_link`, `handle_time`, and optionally `__repr__`.
   - Router implementations are expected to use only the base `send()` method and their own `addr` field from the base class.

6. **Distance-vector subsystem**
   - `DVrouter.py` is the distance-vector implementation.
   - Each router maintains local distance estimates and a forwarding decision for each destination.
   - It reacts to neighbor advertisements, recomputes best next hops, and periodically rebroadcasts its own vector to neighbors.

7. **Link-state subsystem**
   - `LSrouter.py` is the link-state implementation.
   - Each router stores its own link state plus learned link states from other routers.
   - It floods link-state updates with **sequence numbers** to suppress stale information, then recomputes shortest paths from the collected topology.

8. **Topology and event inputs**
   - The `*.json` files at the repo root define test networks, link costs, and sometimes scheduled link failures/additions.
   - Files ending in `_events.json` represent dynamic scenarios where the router must adapt to topology changes over time.

9. **Execution paths**
   - `network.py` runs the simulator headlessly for automated testing.
   - `visualize_network.py` runs the same simulation with a GUI, showing routers, clients, links, packet movement, and the current traced routes.
   - These two entry points are the main way the repository is exercised.

10. **Testing and validation**
   - `test_scripts/test_dv_ls.sh` runs the provided scenarios against either `DVrouter` or `LSrouter`.
   - The end-to-end success criterion is whether traceroute packets follow the expected lowest-cost paths after convergence and after topology events.

11. **Repository boundaries and constraints**
   - The grading boundary is strict: only `DVrouter.py` and `LSrouter.py` should be changed.
   - The simulator, packet model, router base class, and test harness are treated as fixed infrastructure.

12. **Documentation and deliverables**
   - `README.md` is the project spec and usage guide.
   - `report/report.md` is present for writeup/reporting, but the code architecture itself centers on the simulator plus the two router implementations.

Main entry points: [`network.py`](https://github.com/harvard-cs145/routing/blob/main/network.py) (network.py), [`DVrouter.py`](https://github.com/harvard-cs145/routing/blob/main/DVrouter.py) (DVrouter.py), [`LSrouter.py`](https://github.com/harvard-cs145/routing/blob/main/LSrouter.py) (LSrouter.py), [`packet.py`](https://github.com/harvard-cs145/routing/blob/main/packet.py) (packet.py)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime"]
  node_network_py["network.py<br/>simulator<br/>[network.py]"]
  node_visualize_network_py["visualize_network.py<br/>gui simulator"]
end

subgraph group_core["Core model"]
  node_router_py["router.py<br/>base router<br/>[router.py]"]
  node_packet_py["packet.py<br/>packet model<br/>[packet.py]"]
  node_client_py["client.py<br/>client actor<br/>[client.py]"]
  node_link_py["link.py<br/>link model<br/>[link.py]"]
end

subgraph group_algos["Routing algorithms"]
  node_dvrouter_py["DVrouter.py<br/>distance-vector<br/>[DVrouter.py]"]
  node_lsrouter_py["LSrouter.py<br/>link-state<br/>[LSrouter.py]"]
end

subgraph group_inputs["Scenarios"]
  node_small_net_json["01_small_net.json<br/>topology<br/>[01_small_net.json]"]
  node_small_net_events_json["02_small_net_events.json<br/>dynamic topology"]
  node_pg244_net_json["03_pg244_net.json<br/>topology<br/>[03_pg244_net.json]"]
  node_pg244_net_events_json["04_pg244_net_events.json<br/>dynamic topology"]
  node_pg242_net_json["05_pg242_net.json<br/>topology<br/>[05_pg242_net.json]"]
  node_pg242_net_events_json["06_pg242_net_events.json<br/>dynamic topology"]
end

subgraph group_ops["Validation"]
  node_test_script["test_dv_ls.sh<br/>test harness<br/>[test_dv_ls.sh]"]
  node_readme_md["README.md<br/>spec guide<br/>[README.md]"]
  node_report_md["report.md<br/>writeup<br/>[report.md]"]
end

node_network_py -->|"instantiates"| node_router_py
node_network_py -->|"moves packets"| node_packet_py
node_network_py -->|"uses links"| node_link_py
node_network_py -->|"loads"| node_dvrouter_py
node_network_py -->|"loads"| node_lsrouter_py
node_visualize_network_py -->|"wraps"| node_network_py
node_visualize_network_py -->|"shows"| node_client_py
node_router_py -->|"sends"| node_packet_py
node_client_py -->|"creates"| node_packet_py
node_dvrouter_py -->|"extends"| node_router_py
node_dvrouter_py -->|"advertises"| node_packet_py
node_lsrouter_py -->|"extends"| node_router_py
node_lsrouter_py -->|"floods"| node_packet_py
node_small_net_json -->|"inputs"| node_network_py
node_small_net_events_json -->|"inputs"| node_network_py
node_pg244_net_json -->|"inputs"| node_network_py
node_pg244_net_events_json -->|"inputs"| node_network_py
node_pg242_net_json -->|"inputs"| node_network_py
node_pg242_net_events_json -->|"inputs"| node_network_py
node_test_script -->|"runs"| node_network_py
node_test_script -->|"tests"| node_dvrouter_py
node_test_script -->|"tests"| node_lsrouter_py
node_readme_md -->|"documents"| node_network_py
node_readme_md -->|"specifies"| node_dvrouter_py
node_readme_md -->|"specifies"| node_lsrouter_py
node_report_md -->|"describes"| node_dvrouter_py
node_report_md -->|"describes"| node_lsrouter_py

click node_network_py "https://github.com/harvard-cs145/routing/blob/main/network.py"
click node_visualize_network_py "https://github.com/harvard-cs145/routing/blob/main/visualize_network.py"
click node_router_py "https://github.com/harvard-cs145/routing/blob/main/router.py"
click node_packet_py "https://github.com/harvard-cs145/routing/blob/main/packet.py"
click node_client_py "https://github.com/harvard-cs145/routing/blob/main/client.py"
click node_link_py "https://github.com/harvard-cs145/routing/blob/main/link.py"
click node_dvrouter_py "https://github.com/harvard-cs145/routing/blob/main/DVrouter.py"
click node_lsrouter_py "https://github.com/harvard-cs145/routing/blob/main/LSrouter.py"
click node_small_net_json "https://github.com/harvard-cs145/routing/blob/main/01_small_net.json"
click node_small_net_events_json "https://github.com/harvard-cs145/routing/blob/main/02_small_net_events.json"
click node_pg244_net_json "https://github.com/harvard-cs145/routing/blob/main/03_pg244_net.json"
click node_pg244_net_events_json "https://github.com/harvard-cs145/routing/blob/main/04_pg244_net_events.json"
click node_pg242_net_json "https://github.com/harvard-cs145/routing/blob/main/05_pg242_net.json"
click node_pg242_net_events_json "https://github.com/harvard-cs145/routing/blob/main/06_pg242_net_events.json"
click node_test_script "https://github.com/harvard-cs145/routing/blob/main/test_scripts/test_dv_ls.sh"
click node_readme_md "https://github.com/harvard-cs145/routing/blob/main/README.md"
click node_report_md "https://github.com/harvard-cs145/routing/blob/main/report/report.md"

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_network_py,node_visualize_network_py toneBlue
class node_router_py,node_packet_py,node_client_py,node_link_py toneAmber
class node_dvrouter_py,node_lsrouter_py toneMint
class node_small_net_json,node_small_net_events_json,node_pg244_net_json,node_pg244_net_events_json,node_pg242_net_json,node_pg242_net_events_json toneRose
class node_test_script,node_readme_md,node_report_md toneIndigo
```

## Components

### Runtime

Simulator and entry points that drive the routing actors.

- [network.py](https://github.com/harvard-cs145/routing/blob/main/network.py): simulator · Headless simulator that instantiates routers, links, and drives events. · `network.py`
- [visualize_network.py](https://github.com/harvard-cs145/routing/blob/main/visualize_network.py): gui simulator · Interactive simulator front end that visualizes packet movement and routes. · `visualize_network.py`

### Core model

Shared packet, router, client, and link abstractions.

- [router.py](https://github.com/harvard-cs145/routing/blob/main/router.py): base router · Base Router interface and shared send/event hooks for routing actors. · `router.py`
- [packet.py](https://github.com/harvard-cs145/routing/blob/main/packet.py): packet model · Packet representation for client traffic and routing control messages. · `packet.py`
- [client.py](https://github.com/harvard-cs145/routing/blob/main/client.py): client actor · Client-side logic used to inject traceroute-like traffic into the network. · `client.py`
- [link.py](https://github.com/harvard-cs145/routing/blob/main/link.py): link model · Simulated link abstraction connecting routers and carrying packets. · `link.py`

### Routing algorithms

Alternative decentralized routing implementations.

- [DVrouter.py](https://github.com/harvard-cs145/routing/blob/main/DVrouter.py): distance-vector · Distance-vector router implementation with local tables and periodic advertisements. · `DVrouter.py`
- [LSrouter.py](https://github.com/harvard-cs145/routing/blob/main/LSrouter.py): link-state · Link-state router implementation with flooding and shortest-path recomputation. · `LSrouter.py`

### Scenarios

Static and dynamic network definitions used by the simulator.

- [01_small_net.json](https://github.com/harvard-cs145/routing/blob/main/01_small_net.json): topology · Static test network definition. · `01_small_net.json`
- [02_small_net_events.json](https://github.com/harvard-cs145/routing/blob/main/02_small_net_events.json): dynamic topology · Small network scenario with scheduled link events. · `02_small_net_events.json`
- [03_pg244_net.json](https://github.com/harvard-cs145/routing/blob/main/03_pg244_net.json): topology · Larger static network test scenario. · `03_pg244_net.json`
- [04_pg244_net_events.json](https://github.com/harvard-cs145/routing/blob/main/04_pg244_net_events.json): dynamic topology · Larger network scenario with topology changes over time. · `04_pg244_net_events.json`
- [05_pg242_net.json](https://github.com/harvard-cs145/routing/blob/main/05_pg242_net.json): topology · Additional static network test scenario. · `05_pg242_net.json`
- [06_pg242_net_events.json](https://github.com/harvard-cs145/routing/blob/main/06_pg242_net_events.json): dynamic topology · Additional network scenario with failures and recovery events. · `06_pg242_net_events.json`

### Validation

Scripts and docs for running and checking the project.

- [test_dv_ls.sh](https://github.com/harvard-cs145/routing/blob/main/test_scripts/test_dv_ls.sh): test harness · Runs the provided scenarios against DVrouter or LSrouter. · `test_scripts/test_dv_ls.sh`
- [README.md](https://github.com/harvard-cs145/routing/blob/main/README.md): spec guide · Project specification, usage, and expected behavior. · `README.md`
- [report.md](https://github.com/harvard-cs145/routing/blob/main/report/report.md): writeup · Project report and implementation notes. · `report/report.md`

## Connections

- network.py → router.py: instantiates · Creates one router object per node and calls its event hooks.
- network.py → packet.py: moves packets · Delivers client and routing packets through the simulation.
- network.py → link.py: uses links · Builds and updates simulated adjacency between routers.
- network.py → DVrouter.py: loads · Can run the distance-vector algorithm implementation.
- network.py → LSrouter.py: loads · Can run the link-state algorithm implementation.
- visualize_network.py → network.py: wraps · Runs the same simulation with a graphical front end.
- visualize_network.py → client.py: shows · Visualizes client traffic and traced routes.
- router.py → packet.py: sends · Base router send() transmits packets using the shared packet model.
- client.py → packet.py: creates · Builds traceroute-like packets injected into the network.
- DVrouter.py → router.py: extends · Implements router hooks for distance-vector behavior.
- DVrouter.py → packet.py: advertises · Encodes routing updates as packet payloads.
- LSrouter.py → router.py: extends · Implements router hooks for link-state behavior.
- LSrouter.py → packet.py: floods · Encodes and forwards link-state announcements as packets.
- 01_small_net.json → network.py: inputs · Defines one test topology for the simulator.
- 02_small_net_events.json → network.py: inputs · Defines a dynamic topology with scheduled events.
- 03_pg244_net.json → network.py: inputs · Defines one larger test topology.
- 04_pg244_net_events.json → network.py: inputs · Defines a larger dynamic scenario.
- 05_pg242_net.json → network.py: inputs · Defines another test topology.
- 06_pg242_net_events.json → network.py: inputs · Defines another dynamic scenario.
- test_dv_ls.sh → network.py: runs · Executes headless scenarios for automated validation.
- test_dv_ls.sh → DVrouter.py: tests · Validates distance-vector behavior across scenarios.
- test_dv_ls.sh → LSrouter.py: tests · Validates link-state behavior across scenarios.
- README.md → network.py: documents · Explains simulator usage and execution flow.
- README.md → DVrouter.py: specifies · Defines the expected distance-vector implementation behavior.
- README.md → LSrouter.py: specifies · Defines the expected link-state implementation behavior.
- report.md → DVrouter.py: describes · Records implementation details for the routing project.
- report.md → LSrouter.py: describes · Records implementation details for the routing project.
