# zmap/zannotate architecture

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

- Interactive diagram: https://gitdiagram.com/zmap/zannotate
- Repository: https://github.com/zmap/zannotate

## Overview

##### Main Components
- Command Line Interface (CLI) – Represent the various command entry points (e.g., the zannotate command in cmd/zannotate and additional tools like mrt2json).
- Command Modules – Show the “cmd” directory with its subcommands, emphasizing that they serve as the main executables which delegate work to core libraries.
- External Resources – Indicate Maxmind GeoIP2 Database (geoip2.mmdb) as an external dependency, plus the MRT routing data input.
- Auxiliary Tools – Note the presence of the “asnames” Python tool and any other helpers (zmrt, zrouting) that might provide specialized functionality or auxiliary data processing.
- Configuration & Build – Include support files like conf.go, BUILDING.md, .travis.yml (for CI/CD), and go.mod/go.sum, which collectively outline build and dependency management aspects.

##### Relationships and Interactions
- Data Flow: Begin with the input (data piped to the CLI) and show it flowing into the CLI module.
– IPs from the input are passed through the GeoIP2 annotation module (geoip2.go) that interacts with the external Maxmind database.
– For AS/Routing information, data flows into the routing modules (routing.go, parts in zrouting and zmrt) to look up and enrich annotations.

##### Architectural Patterns / Design Principles
- Modular Design: Emphasize that functionality is split across dedicated packages (e.g., one for geoip, one for AS/routing, one for MRT handling). This modularization helps in isolating responsibilities and simplifies testing.
- Separation of Concerns: Differentiate between the CLI “front-end” and the processing “back-end” modules.
- Single Responsibility: Each module (e.g., geoip2.go vs. routing.go) handles one specific part of the overall annotation process.
- Extensibility: With components like asnames in Python and separate command directories, the system is built to allow for new annotation sources or commands to be added.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Input Layer
    I["Input Data (e.g., CSV of IPs)"]:::external

    %% CLI Tools Subgraph
    subgraph "CLI Tools"
        Z["zannotate (cmd/zannotate/main.go)"]:::cli
        M["mrt2json (cmd/mrt2json/main.go)"]:::cli
    end

    %% Core Modules Subgraph
    subgraph "Core Modules"
        G["GeoIP2 Annotation (geoip2.go)"]:::core
        A["AS/ASN Annotation (geoipasn.go)"]:::core
        RDNS["Reverse DNS Lookup (rdns.go)"]:::core
        R["Routing Annotation (routing.go)"]:::core
    end

    %% Auxiliary Tools Subgraph
    subgraph "Auxiliary Tools"
        AN["AS Names Helper (asnames/__main__.py)"]:::auxiliary
        ZMRT["MRT Data Processing (zmrt/mrt.go)"]:::auxiliary
        ZRL["Routing Data Lookup (zrouting/routinglookup.go)"]:::auxiliary
    end

    %% External Resources Subgraph
    subgraph "External Resources"
        MG["Maxmind GeoIP2 Database"]:::external
        MRT["MRT Routing Data"]:::external
    end

    %% Configuration & Build Subgraph
    subgraph "Configuration & Build"
        CONF["General Configurations (conf.go)"]:::config
        BUILD["CI/CD & Build Docs (.travis.yml, BUILDING.md, go.mod, go.sum)"]:::config
    end

    %% Data Flow Connections
    I -->|"ingests"| Z
    I -->|"ingests"| M

    Z -->|"handles IP input"| G
    Z -->|"handles IP input"| A
    Z -->|"handles IP input"| RDNS
    Z -->|"handles IP input"| R

    %% External interactions from core modules
    G -->|"queries"| MG

    R -->|"accesses"| MRT
    R -->|"utilizes"| ZMRT
    R -->|"utilizes"| ZRL

    A -->|"maps AS numbers"| AN

    %% Click Events
    click Z "https://github.com/zmap/zannotate/blob/master/cmd/zannotate/main.go"
    click M "https://github.com/zmap/zannotate/blob/master/cmd/mrt2json/main.go"
    click G "https://github.com/zmap/zannotate/blob/master/geoip2.go"
    click A "https://github.com/zmap/zannotate/blob/master/geoipasn.go"
    click RDNS "https://github.com/zmap/zannotate/blob/master/rdns.go"
    click R "https://github.com/zmap/zannotate/blob/master/routing.go"
    click AN "https://github.com/zmap/zannotate/blob/master/asnames/__main__.py"
    click ZMRT "https://github.com/zmap/zannotate/blob/master/zmrt/mrt.go"
    click ZRL "https://github.com/zmap/zannotate/blob/master/zrouting/routinglookup.go"
    click CONF "https://github.com/zmap/zannotate/blob/master/conf.go"

    %% Styles
    classDef cli fill:#FFDC00,stroke:#333,stroke-width:2px;
    classDef core fill:#ABEBE6,stroke:#333,stroke-width:2px;
    classDef auxiliary fill:#C4DEF6,stroke:#333,stroke-width:2px;
    classDef external fill:#FFC0CB,stroke:#333,stroke-width:2px;
    classDef config fill:#E2F0CB,stroke:#333,stroke-width:2px;
```
