# natesales/pathvector architecture

> Architecture diagram of the GitHub repository natesales/pathvector, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-11). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/natesales/pathvector
- Repository: https://github.com/natesales/pathvector

## Overview

##### Project Type & Purpose
- This is a declarative edge routing platform designed to automate BGP route optimization, filtering, and control plane configuration. Its purpose is to allow network operators to manage routing policies in a robust and repeatable way.
- The READMEs and file organization indicate that it is primarily a command-line/go application with modular packages to handle different parts of the BGP ecosystem—such as route filtering (IRR, ASPA, etc.), optimization based on latency/packet loss, vendor-specific templating, and automated configuration sourcing from external systems like PeeringDB.

##### Main Components
a. CLI/Command Layer:
- Represented by the main entry points in the “cmd” directory (e.g., birdsh.go, generate.go, dump.go, match.go, optimizer.go, etc.).
- This layer handles user interactions and command execution.
b. Core Business Logic Modules:
- Routing Filtering & Matching: Packages such as pkg/irr and pkg/match, which implement IRR checks and route matching functions.
- Route Optimization: The pkg/optimizer module that enriches and optimizes routes with latency and packet loss metrics.
- Configuration Management: pkg/config handles the configuration parsing, while pkg/templating and pkg/embed are responsible for generating configuration outputs (using templates like bird, peer, ui, and vrrp).
c. External Integration:
- Automatic Configuration from PeeringDB: Represent the pkg/peeringdb module, which pulls data from external BGP databases.
- Vendor-specific Builds: The “vendorbuild” directory shows specific integration points (Arista, Cisco, Juniper, Mikrotik). Indicate these as external adapters or interfaces to various network device platforms.
d. Extensibility & Plugins:
- The pkg/plugin and pkg/process directories highlight the Go plugin API and general process management for dynamically loaded functionality.
e. Auxiliary and Testing Infrastructure:
- Although not part of the core runtime pipeline, include representations for tests (from the tests directory) and CI/CD (GitHub workflows, Makefile, and related config files) which ensure system quality.
f. Documentation:

##### Relationships & Interactions
- Data flow from user-defined declarative configurations (entered by operators and typically maintained in version control) into the configuration management system.
- That once configurations are parsed, the templating engine (pkg/templating, pkg/embed) generates the final configuration output that is targeted towards the correct network device platform (via vendor-specific modules in vendorbuild).
- Link external data sources (like PeeringDB API) to the configuration/optimization modules, indicating a data pull that enriches the route data.
- Plugin subsystem as an optional extension point interacting with the main data processing pipeline.

##### Architectural Patterns and Design Principles
- Modular design: Each package is focused on a single responsibility (e.g., matching routes, handling IRR, or templating configurations).
- Declarative Configuration: The model allows for committing desired state to VCS, triggering rebuilds/configuration generation.
- Extensibility: The plugin API permits customized extensions, so indicate this loosely coupled plugin interface that hooks into the main computation flow.

##### Elements
- Each major module should be clearly labeled (e.g., “CLI Command Layer”, “Configuration Parser”, “Route Matching Engine”, “Route Optimizer”, “PeeringDB Integration”, “Templating Engine”, “Vendor-Specific Adapter”).
⁃ How the CLI invokes commands that traverse into configuration parsing and processing.
⁃ The data flow from external systems (PeeringDB/API) to core modules.
⁃ The output path from templating generation to the end user or target devices.
- Optionally, include notes on technologies (e.g., written in Go, using Docusaurus for documentation, deploying scripts and workflows for CI/CD).

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% CLI Layer
    A["CLI Command Layer"]:::cli

    %% Business Logic Modules
    subgraph "Business Logic"
        E["Configuration Management (pkg/config)"]:::business
        B["IRR Engine (pkg/irr)"]:::business
        C["Match Engine (pkg/match)"]:::business
        D["Route Optimizer (pkg/optimizer)"]:::business
    end

    %% Templating and Output Generation
    F["Templating & Config Output (pkg/templating & pkg/embed)"]:::templating

    %% External Integration and Vendor Adapter
    G["PeeringDB Integration (pkg/peeringdb)"]:::integration
    H["Vendor-Specific Adapter (vendorbuild)"]:::vendor

    %% Plugin and Process Extensibility
    I["Plugin & Process Extensibility (pkg/plugin & pkg/process)"]:::plugin

    %% Auxiliary Testing Infrastructure and Documentation
    J["Testing & CI/CD (tests)"]:::testing
    K["Documentation (docs)"]:::docs

    %% Relationships and Data Flows
    A -->|"triggers"| E
    A -->|"invokes"| B
    A -->|"invokes"| C
    A -->|"invokes"| D
    A -->|"optionalPlugin"| I

    E -->|"passesData"| F
    G -->|"feedsData"| D
    F -->|"generatesOutputFor"| H

    I -->|"extends"| E
    I -->|"extends"| D
    I -->|"addsCustomLogic"| B
    I -->|"addsCustomLogic"| C

    %% Styles
    classDef cli fill:#AEDFF7,stroke:#000,stroke-width:2px;
    classDef business fill:#CFF0CC,stroke:#000,stroke-width:2px;
    classDef templating fill:#F9E2AE,stroke:#000,stroke-width:2px;
    classDef integration fill:#FFD2A7,stroke:#000,stroke-width:2px;
    classDef vendor fill:#E1C6F8,stroke:#000,stroke-width:2px;
    classDef plugin fill:#FFB6C1,stroke:#000,stroke-width:2px;
    classDef testing fill:#E6E6E6,stroke:#000,stroke-width:2px;
    classDef docs fill:#D0E9FF,stroke:#000,stroke-width:2px;

    %% Click Events
    click A "https://github.com/natesales/pathvector/tree/main/cmd"
    click B "https://github.com/natesales/pathvector/blob/main/pkg/irr/irr.go"
    click C "https://github.com/natesales/pathvector/blob/main/pkg/match/match.go"
    click D "https://github.com/natesales/pathvector/blob/main/pkg/optimizer/optimizer.go"
    click E "https://github.com/natesales/pathvector/blob/main/pkg/config/config.go"
    click F "https://github.com/natesales/pathvector/blob/main/pkg/templating/templating.go"
    click F "https://github.com/natesales/pathvector/blob/main/pkg/embed/embed.go"
    click F "https://github.com/natesales/pathvector/tree/main/pkg/embed/templates"
    click G "https://github.com/natesales/pathvector/blob/main/pkg/peeringdb/peeringdb.go"
    click H "https://github.com/natesales/pathvector/tree/main/vendorbuild"
    click I "https://github.com/natesales/pathvector/blob/main/pkg/plugin/plugin.go"
    click I "https://github.com/natesales/pathvector/blob/main/pkg/process/pluginloader.go"
    click J "https://github.com/natesales/pathvector/tree/main/tests"
    click K "https://github.com/natesales/pathvector/tree/main/docs"
```
