# annetutil/annet architecture

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

- Interactive diagram: https://gitdiagram.com/annetutil/annet
- Repository: https://github.com/annetutil/annet

## Overview

#### Purpose and entry points
Annet is a Python CLI/library for intent-based network configuration generation, comparison with device state, command-patch creation, and deployment. Main entry points are `annet/__main__.py`, `annet/cli.py`, and the package orchestration modules `annet/gen.py`, `annet/diff.py`, and `annet/deploy.py`. The root `annet.py` is also a top-level launcher.

#### Command pipeline
The primary control flow is progressive: `gen` creates desired configuration, `diff` obtains current configuration and compares it, `patch` converts the difference into device commands, and `deploy` applies those commands. Core stages reside in `annet/gen.py`, `annet/diff.py`, `annet/patching.py`, and `annet/deploy.py`. CLI argument parsing and command selection are separated into `annet/argparse.py` and `annet/cli_args.py`.

#### Context, storage, and adapters
Runtime behavior is selected through a context containing generator and storage definitions. Storage is an abstraction boundary between Annet and inventory/source-of-truth systems: file-backed input is implemented at `annet/adapters/file/provider.py`; NetBox integration begins at `annet/adapters/netbox/provider.py` and version-specific storage implementations are in `annet/adapters/netbox/v37/storage.py`, `annet/adapters/netbox/v41/storage.py`, and `annet/adapters/netbox/v42/storage.py`. NetBox is the material external service; adapters also include stub fetch/deploy implementations for extension or testing.

#### Desired-state generation
User-supplied Python generator packages produce full or partial desired device configuration. The generator framework defines execution modes, results, references, annotation, and failure handling in `annet/generators/base.py`, `annet/generators/entire.py`, `annet/generators/partial.py`, and `annet/generators/result.py`. Example extension packages under `annet_generators/` demonstrate the intended plugin boundary rather than being core production logic.

#### Device and vendor modeling
Device identity, hardware/platform handling, and vendor selection are centralized in `annet/hardware.py`, `annet/vendors/registry.py`, and `annet/vendors/base.py`. Vendor libraries map supported platforms such as Cisco, Huawei, Juniper, Arista, and RouterOS to behavior in paths such as `annet/vendors/library/cisco.py`, `annet/vendors/library/huawei.py`, and `annet/vendors/library/juniper.py`. A bundled device database supports network-device metadata at `annet/annlib/netdev/devdb/data/devdb.json`.

#### Diff, parsing, and patch compilation
Annet parses hierarchical network configurations, computes structural differences, then compiles vendor-specific command sequences. Shared mechanics are in `annet/annlib/diff.py`, `annet/annlib/patching.py`, and `annet/annlib/rbparser/`. The parser/rulebook boundary allows generic config changes to be rendered differently per platform; deployment-aware parsing is specifically represented by `annet/annlib/rbparser/deploying.py`.

#### Rulebooks and deployment
Rulebooks encode platform syntax, ordering, replacement/removal semantics, and deploy transformations. Python rule logic is organized by vendor under `annet/rulebook/` (for example `annet/rulebook/huawei/`, `annet/rulebook/cisco/`, `annet/rulebook/juniper/`), while declarative rule assets are under `annet/rulebook/texts/`, including `annet/rulebook/texts/huawei.rul`, `annet/rulebook/texts/cisco.deploy`, and `annet/rulebook/texts/juniper.order`. Deployment execution and UI-oriented handling are separated into `annet/deploy.py` and `annet/deploy_ui.py`.

#### Higher-level network policy features
The repository includes two domain layers usable by generators: mesh/BGP topology processing in `annet/mesh/executor.py`, `annet/mesh/registry.py`, and `annet/mesh/port_processor.py`; and routing-policy modeling/rendering in `annet/rpl/policy.py`, `annet/rpl/routemap.py`, and `annet/rpl_generators/execute.py`. These produce configuration intent before the central generation-to-deployment pipeline.

Main entry points: [`annet/gen.py`](https://github.com/annetutil/annet/blob/main/annet/gen.py) (Desired config generation), [`annet/cli.py`](https://github.com/annetutil/annet/blob/main/annet/cli.py) (Command selection), [`annet/diff.py`](https://github.com/annetutil/annet/blob/main/annet/diff.py) (Current-state diff), [`annet/adapters/file/provider.py`](https://github.com/annetutil/annet/blob/main/annet/adapters/file/provider.py) (Storage abstraction)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["CLI & Orchestration"]
  node_launcher["CLI launchers<br/>Python entry points<br/>[__main__.py]"]
  node_cli["Command selection<br/>CLI<br/>[cli.py]"]
  node_cli_args["CLI arguments<br/>argument parsing<br/>[argparse.py]"]
  node_generation["Desired config generation<br/>orchestrator<br/>[gen.py]"]
  node_diff_stage["Current-state diff<br/>orchestrator<br/>[diff.py]"]
end

subgraph group_intent["Intent Sources"]
  node_generator_plugins{{"Generator packages<br/>plugin boundary"}}
  node_generator_framework["Generator framework<br/>execution model<br/>[base.py]"]
  node_mesh["Mesh/BGP intent<br/>domain layer<br/>[executor.py]"]
  node_routing_policy["Routing policy intent<br/>domain layer<br/>[execute.py]"]
end

subgraph group_inventory["Inventory &amp; Device Model"]
  node_storage{{"Storage abstraction<br/>inventory boundary<br/>[provider.py]"}}
  node_netbox_adapter{{"NetBox adapters<br/>external adapter<br/>[provider.py]"}}
  node_netbox[("NetBox<br/>external service")]
  node_device_model["Hardware &amp; vendor model<br/>platform selection<br/>[hardware.py]"]
  node_vendor_libraries["Vendor libraries<br/>platform behavior<br/>[registry.py]"]
end

subgraph group_compile["Diff &amp; Patch Compilation"]
  node_structural_diff["Structural config diff<br/>configuration engine<br/>[diff.py]"]
  node_patch_compiler["Command patch compiler<br/>configuration engine<br/>[patching.py]"]
end

subgraph group_delivery["Rulebooks &amp; Deployment"]
  node_rulebooks["Vendor rulebooks<br/>syntax and ordering rules"]
  node_deployment_parser["Deployment-aware parser<br/>rulebook parser<br/>[deploying.py]"]
  node_deploy["Deployment execution<br/>orchestrator<br/>[deploy.py]"]
  node_devices(("Network devices<br/>deployment target"))
end

node_launcher -->|"starts"| node_cli
node_cli -->|"parses"| node_cli_args
node_cli -->|"gen"| node_generation
node_cli -->|"diff / patch"| node_diff_stage
node_cli -->|"deploy"| node_deploy
node_generator_plugins -->|"implements"| node_generator_framework
node_mesh -->|"topology intent"| node_generation
node_routing_policy -->|"policy intent"| node_generation
node_generator_framework -->|"executes"| node_generation
node_storage -->|"inventory/context"| node_generation
node_netbox_adapter -->|"implements"| node_storage
node_netbox_adapter -->|"queries"| node_netbox
node_storage -->|"current state"| node_diff_stage
node_device_model -->|"selects vendor"| node_vendor_libraries
node_vendor_libraries -->|"platform behavior"| node_generation
node_generation -->|"desired config"| node_diff_stage
node_diff_stage -->|"compares configs"| node_structural_diff
node_structural_diff -->|"changes"| node_patch_compiler
node_vendor_libraries -->|"selects rules"| node_rulebooks
node_rulebooks -->|"deploy rules"| node_deployment_parser
node_patch_compiler -->|"command plan"| node_deployment_parser
node_deployment_parser -->|"transformed commands"| node_deploy
node_deploy -->|"applies"| node_devices

click node_launcher "https://github.com/annetutil/annet/blob/main/annet/__main__.py"
click node_cli "https://github.com/annetutil/annet/blob/main/annet/cli.py"
click node_cli_args "https://github.com/annetutil/annet/blob/main/annet/argparse.py"
click node_generation "https://github.com/annetutil/annet/blob/main/annet/gen.py"
click node_diff_stage "https://github.com/annetutil/annet/blob/main/annet/diff.py"
click node_generator_framework "https://github.com/annetutil/annet/blob/main/annet/generators/base.py"
click node_mesh "https://github.com/annetutil/annet/blob/main/annet/mesh/executor.py"
click node_routing_policy "https://github.com/annetutil/annet/blob/main/annet/rpl_generators/execute.py"
click node_storage "https://github.com/annetutil/annet/blob/main/annet/adapters/file/provider.py"
click node_netbox_adapter "https://github.com/annetutil/annet/blob/main/annet/adapters/netbox/provider.py"
click node_device_model "https://github.com/annetutil/annet/blob/main/annet/hardware.py"
click node_vendor_libraries "https://github.com/annetutil/annet/blob/main/annet/vendors/registry.py"
click node_structural_diff "https://github.com/annetutil/annet/blob/main/annet/annlib/diff.py"
click node_patch_compiler "https://github.com/annetutil/annet/blob/main/annet/annlib/patching.py"
click node_deployment_parser "https://github.com/annetutil/annet/blob/main/annet/annlib/rbparser/deploying.py"
click node_deploy "https://github.com/annetutil/annet/blob/main/annet/deploy.py"

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_launcher,node_cli,node_cli_args,node_generation,node_diff_stage toneBlue
class node_generator_plugins,node_generator_framework,node_mesh,node_routing_policy toneAmber
class node_storage,node_netbox_adapter,node_netbox,node_device_model,node_vendor_libraries toneMint
class node_structural_diff,node_patch_compiler toneRose
class node_rulebooks,node_deployment_parser,node_deploy,node_devices toneIndigo
```

## Components

### CLI & Orchestration

- [CLI launchers](https://github.com/annetutil/annet/blob/main/annet/__main__.py): Python entry points · `annet/__main__.py`
- [Command selection](https://github.com/annetutil/annet/blob/main/annet/cli.py): CLI · Parses arguments and selects gen, diff, patch, or deploy. · `annet/cli.py`
- [CLI arguments](https://github.com/annetutil/annet/blob/main/annet/argparse.py): argument parsing · `annet/argparse.py`
- [Desired config generation](https://github.com/annetutil/annet/blob/main/annet/gen.py): orchestrator · `annet/gen.py`
- [Current-state diff](https://github.com/annetutil/annet/blob/main/annet/diff.py): orchestrator · `annet/diff.py`

### Intent Sources

- **Generator packages**: plugin boundary · User Python generators produce full or partial device intent.
- [Generator framework](https://github.com/annetutil/annet/blob/main/annet/generators/base.py): execution model · Defines generator modes, results, references, and failure handling. · `annet/generators/base.py`
- [Mesh/BGP intent](https://github.com/annetutil/annet/blob/main/annet/mesh/executor.py): domain layer · `annet/mesh/executor.py`
- [Routing policy intent](https://github.com/annetutil/annet/blob/main/annet/rpl_generators/execute.py): domain layer · `annet/rpl_generators/execute.py`

### Inventory & Device Model

- [Storage abstraction](https://github.com/annetutil/annet/blob/main/annet/adapters/file/provider.py): inventory boundary · Selects source-of-truth and generator definitions through runtime context. · `annet/adapters/file/provider.py`
- [NetBox adapters](https://github.com/annetutil/annet/blob/main/annet/adapters/netbox/provider.py): external adapter · Version-specific storage adapters integrate with NetBox. · `annet/adapters/netbox/provider.py`
- **NetBox**: external service
- [Hardware & vendor model](https://github.com/annetutil/annet/blob/main/annet/hardware.py): platform selection · `annet/hardware.py`
- [Vendor libraries](https://github.com/annetutil/annet/blob/main/annet/vendors/registry.py): platform behavior · Maps supported network platforms to vendor behavior. · `annet/vendors/registry.py`

### Diff & Patch Compilation

- [Structural config diff](https://github.com/annetutil/annet/blob/main/annet/annlib/diff.py): configuration engine · Parses hierarchical configuration and computes changes. · `annet/annlib/diff.py`
- [Command patch compiler](https://github.com/annetutil/annet/blob/main/annet/annlib/patching.py): configuration engine · Compiles configuration differences into device commands. · `annet/annlib/patching.py`

### Rulebooks & Deployment

- **Vendor rulebooks**: syntax and ordering rules · Encodes platform syntax, ordering, replacement, removal, and deploy transformations.
- [Deployment-aware parser](https://github.com/annetutil/annet/blob/main/annet/annlib/rbparser/deploying.py): rulebook parser · `annet/annlib/rbparser/deploying.py`
- [Deployment execution](https://github.com/annetutil/annet/blob/main/annet/deploy.py): orchestrator · Applies compiled command patches to devices. · `annet/deploy.py`
- **Network devices**: deployment target

## Connections

- CLI launchers → Command selection: starts
- Command selection → CLI arguments: parses
- Command selection → Desired config generation: gen
- Command selection → Current-state diff: diff / patch
- Command selection → Deployment execution: deploy
- Generator packages → Generator framework: implements
- Mesh/BGP intent → Desired config generation: topology intent
- Routing policy intent → Desired config generation: policy intent
- Generator framework → Desired config generation: executes
- Storage abstraction → Desired config generation: inventory/context
- NetBox adapters → Storage abstraction: implements
- NetBox adapters → NetBox: queries
- Storage abstraction → Current-state diff: current state
- Hardware & vendor model → Vendor libraries: selects vendor
- Vendor libraries → Desired config generation: platform behavior
- Desired config generation → Current-state diff: desired config
- Current-state diff → Structural config diff: compares configs
- Structural config diff → Command patch compiler: changes
- Vendor libraries → Vendor rulebooks: selects rules
- Vendor rulebooks → Deployment-aware parser: deploy rules
- Command patch compiler → Deployment-aware parser: command plan
- Deployment-aware parser → Deployment execution: transformed commands
- Deployment execution → Network devices: applies