Topology Mapping
Relevant source files
The following files were used as context for generating this wiki page:
Overview
Topology Mapping provides network engineers with a living map of their infrastructure, automatically tracking how every device, interface, subnet, and VLAN connects to everything else. This feature solves the problem of stale, manual network diagrams by using discovery data to project a real-time graph of Layer 2 and Layer 3 relationships.
Sources: README.md, CLAUDE.md
The platform supports a wide range of vendors, including Cisco (IOS, IOS-XE, NX-OS), Juniper, Arista, Palo Alto, Fortinet, F5, and DDI providers like Infoblox and BlueCat. The system is designed to be local-first and self-hosted, ensuring that all network data stays within your perimeter. A key design principle is that every AI-proposed change requires a human to approve it, with all AI reasoning visible and audited.
Sources: CLAUDE.md:16-30, README.md:3-9
Specialized Team Members (Agents)
The platform uses specialized "Agents," which you can think of as expert team members that the system routes your questions to:
- Discovery Agent: Specialized in finding new devices and inventory.
- Troubleshooting Agent: Focused on diagnosing routing, BGP, OSPF, and firewall issues.
- Documentation Agent: Responsible for generating diagrams (like the topology map) and runbooks.
- DDI Agent: Handles DNS, DHCP, and IPAM changes.
Sources: CLAUDE.md:42-52, backend/app/agents/ddi/agent.py:46-56
Architecture
The platform is composed of seven primary components that work together to maintain and display your network map:
- frontend: The operations console where you chat with agents and view the live topology map.
- api: The central communication hub that manages agent sessions and coordinates between the frontend and backend.
- worker: The background engine that runs discovery jobs, builds topology maps, and takes config backups without blocking your session.
- postgres: The system of record that stores all discovered data, device inventory, and change request logs.
- neo4j: A living topology map (graph database) that tracks the complex connections between devices, interfaces, and subnets.
- redis: A high-speed cache and messenger that helps the worker communicate with the API.
- ollama: The optional local engine that provides AI brains (LLM inference) for analyzing your network.
Sources: README.md:14-25, deploy/docker/README.md:7-15
Vendor Normalization
To support diverse hardware, the platform uses a standardized connector for each vendor. Whether the system is talking to a Cisco switch or an Infoblox manager, the vendor plugin normalizes the output into a consistent format. This allows the topology engine to map connections without needing to understand the specific command syntax of every different device.
Sources: README.md:27-30, backend/app/plugins/vendors/cisco_nxos/parsers.py:1-15
Deployment Options
Network teams can deploy the platform in two ways:
- Docker Compose: Ideal for labs or small teams, running the entire stack on a single server.
- Kubernetes/Helm: Designed for production environments, providing a multi-node, highly available setup that can withstand server failures.
Sources: README.md:37-45, deploy/kubernetes/netops/README.md:1-15
Topology Data Model
The topology map is built by deriving relationships from normalized discovery data. The platform tracks specific node types and their interconnections.
Key Components and Relationships
| Relationship Type | Source Node | Target Node | Description |
|---|---|---|---|
| HAS_INTERFACE | Device | Interface | Links a physical or logical interface to its host device. |
| CONNECTED_TO | Interface/Device | Interface/Device | Represents a Layer 2 connection (e.g., via LLDP/CDP). |
| IN_SUBNET | Interface | Subnet | Maps an interface to its IP subnet based on addressing. |
| ROUTES_TO | Device | Subnet | Represents Layer 3 reachability or static/dynamic routes. |
| MEMBER_OF | Interface | VLAN | Tracks VLAN membership for switch ports. |
| Sources: backend/tests/workers/test_topology_tasks.py:146-168, frontend/src/tests/TopologyPage.test.tsx:112-126 |
Data Model Visual
This diagram shows "what the platform knows about your network" and how these items relate to one another.
The topology engine links devices through discovery protocols and IP addressing to form a complete graph.
Sources: CLAUDE.md:65-71, backend/tests/workers/test_topology_tasks.py:146-155
System Operations and Flows
System Overview
The following diagram illustrates how users interact with the platform and how the platform connects to your infrastructure.
The platform acts as a central hub between the engineer and the multi-vendor network environment.
Sources: README.md:14-30, CLAUDE.md:16-30
Change Approval Workflow
Every change requested via the platform follows a strict safety lifecycle. A pre-change config backup is always taken before execution.
This process ensures that no change is made to the production network without a second human verifying the action.
Sources: README.md:8-10, deploy/docker/README.md:46-50
Visualizing the Topology
The frontend uses the TopologyPage to render the data stored in Neo4j. Engineers can filter the map by Layer 2 (physical/link) or Layer 3 (IP/routing) views.
Interactive Features
- Layer Toggling: Switch between L2 and L3 views to focus on physical cabling or logical routing.
- Drift Detection: Compare two different discovery runs to see exactly what changed in the topology (e.g., an interface going down or a new neighbor appearing).
- Detail Panel: Clicking a device or interface node pulls up live data like management IP, model, status, and associated subnets.
Sources: frontend/src/tests/TopologyPage.test.tsx:185-220, frontend/src/tests/TopologyPage.test.tsx:238-260
Topology Mapping Logic
The platform reconstructs the topology using "Rebuild Isomorphism." This means the graph in Neo4j can be completely deleted and then perfectly recreated using only the data stored in the Postgres inventory. This ensures the map is always traceable back to real discovery data.
Sources: backend/tests/engines/topology/test_rebuild_exit_criteria.py:14-25, backend/tests/engines/topology/test_rebuild_exit_criteria.py:220-235
Summary
Topology Mapping in the AI Network Operations Platform provides a reliable, automated, and multi-vendor view of the network. By projecting discovered facts into a Neo4j graph, it enables engineers to visualize complex L2/L3 relationships, detect infrastructure changes, and troubleshoot connectivity issues with the help of specialized AI agents, all while maintaining strict human-in-the-loop security controls.