Topology Visualization

Overview

Topology Visualization provides network engineers with a live, interactive map of their infrastructure. It acts as a digital twin of the physical and logical network, allowing teams to visualize how devices, interfaces, subnets, and VLANs are interconnected.

The platform solves the problem of stale static diagrams by automatically discovering the network and projecting it into a graph database (Neo4j). This "living topology map" tracks relationships in real-time, supporting multi-vendor environments including Cisco (IOS, NX-OS), Juniper, Arista, Palo Alto, and cloud providers like AWS and Azure.

Key Design Philosophy

• Local-First & Self-Hosted: The platform and all its data reside within your own infrastructure for maximum security.
• Human-in-the-Loop: Every change identified via the topology or agents requires human approval before execution.
• Auditability: Every decision made by the AI and every change to the topology data is logged and visible.

Specialist Agents

The platform utilizes specialized "team members" known as agents to handle specific tasks:

• Discovery Agent: Performs scans to find new devices and connections.
• Troubleshooting Agent: Diagnoses routing, BGP, OSPF, and reachability issues.
• Documentation Agent: Generates diagrams (Mermaid format) and inventory reports.
• DDI Agent: Manages DNS, DHCP, and IP addresses.

Sources: README.md, CLAUDE.md, backend/app/agents/documentation/agent.py:12-25

Architecture

The platform consists of seven core components working together to maintain and display the network map:

• Frontend: The web console where engineers view the topology, chat with the AI, and approve changes.
• API: The central post office that handles requests from the web console and coordinates between the database and the workers.
• Worker: The background engine that runs discovery jobs, takes configuration backups, and captures packets without blocking your session.
• Postgres: The main database (system of record) that stores device details, user accounts, and change logs.
• Neo4j: A specialized graph database that acts as the living topology map, tracking how everything in the network connects to everything else.
• Redis: A fast, temporary storage area used to manage the queue of tasks for the workers.
• Ollama: An optional component that runs local AI models so your data never has to leave your network.

Sources: README.md, deploy/docker/README.md

Vendor Plugin System

The platform uses a standardized connector for each vendor. Whether the platform is talking to a Cisco router, a Juniper switch, or a BlueCat Address Manager, the plugin normalizes the output into a consistent format before the topology engine processes it.

Sources: README.md, backend/app/agents/documentation/agent.py:32-35

Deployment Options

1. Docker Compose: A single-server deployment ideal for lab environments or small teams. All components run as containers on one machine.
2. Kubernetes/Helm: A production-grade deployment for larger environments, offering high availability across multiple physical nodes.

Sources: deploy/docker/README.md, deploy/kubernetes/netops/README.md:12-20

System Visualizations

Platform Connectivity

This diagram shows how users interact with the platform and how the platform communicates with your infrastructure and external services.

Topology Data Model

This represents "what the platform knows about your network" and how those pieces of information relate to one another.

Change Approval Workflow

Every request to modify the network follows a strict lifecycle to ensure safety.

Topology Functionality

Visual Mapping

The frontend uses Cytoscape.js to render the data stored in Neo4j into a visual graph. Engineers can toggle between different views to focus on specific network layers.

Sources: frontend/src/pages/TopologyPage.tsx:180-210, frontend/src/pages/topology-graph.ts

Run-to-Run Comparison

The platform allows engineers to compare the topology between two different discovery runs. This is critical for identifying "drift" or unexpected changes in the network layout.

Data Mapping Implementation

The platform maps database nodes and edges to visual elements. For example, a Device node is labeled by its hostname, while a Subnet node is labeled by its CIDR block.

// Example of how data is converted for the visual map
// Source: frontend/src/pages/topology-graph.ts:35-50
export function toCytoscapeElements(graph: TopologyGraph) {
  const nodes = graph.nodes.map(node => ({
    data: {
      id: node.key,
      label: node.label,
      // Use hostname for devices, CIDR for subnets
      display: node.label === 'Device' ? node.properties.hostname : node.properties.cidr
    },
    classes: node.label
  }));
  
  // ... maps edges similarly
}

Summary

Topology Visualization in the AI Network Operations Platform provides an automated, multi-vendor view of the network. By projecting discovered inventory into a Neo4j graph, the platform enables engineers to visualize physical and logical connections, compare network states over time, and provide the necessary context for AI-driven troubleshooting and documentation. Every piece of data is gathered locally and every change suggested via the topology remains subject to human oversight.