The Living Topology Graph
Relevant source files
The following files were used as context for generating this wiki page:
Overview
The AI Network Operations Platform is a self-hosted AI assistant designed to act as an "AI Network Engineer" for enterprise teams. It solves the problem of managing complex, multi-vendor environments by providing a single point of interaction where engineers can use plain English to discover infrastructure, troubleshoot issues, and manage changes.
The platform's core design philosophy is local-first and secure-by-default. It is intended to be self-hosted on-premises so that sensitive network data never leaves your control. Crucially, while the AI can draft changes and diagnose faults, a human must approve every change before it is executed, and all AI reasoning is visible and audited.
The platform supports a wide array of vendors and protocols, including:
- Routing/Switching: Cisco (IOS, IOS-XE, NX-OS), Juniper (JunOS), Arista (EOS).
- Security: Palo Alto (PAN-OS), Fortinet (FortiOS).
- Application/Cloud: F5 (BIG-IP), AWS, Azure, VMware.
- DDI (DNS, DHCP, IPAM): BlueCat, Infoblox.
Within the platform, "agents" function like specialized team members. When you ask a question, the Master Architect routes it to the appropriate specialist:
- Discovery Agent: Performs scans and builds the initial inventory.
- Troubleshooting Agent: Diagnoses live routing, BGP, or OSPF faults.
- DDI Agent: Manages DNS records and DHCP scopes.
- Documentation Agent: Generates diagrams and network inventories.
Sources: README.md:3-33, CLAUDE.md:3-23, backend/app/agents/documentation/agent.py:46-75
System Interactions
This diagram shows how users interact with the platform and how the platform connects to your infrastructure.
Architecture
The platform consists of seven core components that work together to maintain the living topology map:
- frontend: The web console where you chat with the AI, view the topology map, and approve changes.
- api: The central brain that handles requests, manages security (authentication), and tracks agent sessions.
- worker: The background engine that performs the heavy lifting, such as running discovery jobs, taking config backups, and processing topology updates without blocking your console session.
- postgres: The "System of Record" that stores the primary inventory, logs, and settings in a traditional database.
- neo4j: The "Living Topology Map." This graph database tracks how devices, interfaces, subnets, and applications connect to one another.
- redis: A high-speed temporary storage used for managing the background job queues and caching data.
- ollama: An optional component that runs the AI models locally on your hardware for maximum privacy.
Sources: README.md:33-41, deploy/docker/README.md:7-15
Vendor Normalization
The platform uses a standardized connector (plugin system) for each vendor. Whether you are querying a Cisco router via SSH or a BlueCat Address Manager via API, the platform normalizes the raw output into a consistent format before the AI or the topology engine processes it.
Sources: README.md:43-46, CLAUDE.md:65-71
Deployment Options
There are two primary ways to deploy the platform:
- Docker Compose: Ideal for labs or small teams. It runs everything on a single server using a single command.
- Kubernetes (Helm): The production standard. It supports multi-node, highly available setups with hardened security policies.
Sources: README.md:48-63, deploy/kubernetes/netops/README.md:7-14
Agent Routing and Workflow
Every user request follows a structured path from intent to execution. The Master Architect ensures that the right specialist handles the job.
Change Approval Workflow
Every change (like adding a DNS record or modifying a firewall rule) follows a strict lifecycle:
- Draft: The AI proposes a change request.
- Pending Approval: A second human must review and approve the request in the console.
- Executing: Once approved, a pre-change config backup is taken, and the Automation Agent deploys the change.
- Completed / Rolled Back: The platform verifies the change. If it fails, it can be rolled back to the previous backup.
Sources: deploy/docker/README.md:48-55, backend/app/agents/ddi/agent.py:18-28
Topology Data Model
The topology graph is a "projection" of the data stored in Postgres. It is designed to be completely rebuildable; if the Neo4j database is lost, the platform can reconstruct the entire map from the inventory in Postgres.
The graph tracks the following relationships, which define "what the platform knows about your network":
| Entity | Description | Relationships |
|---|---|---|
| Device | A physical or virtual node (Router, Switch, Firewall). | HAS_INTERFACE |
| Interface | A physical port or logical interface on a device. | IN_SUBNET, CONNECTED_TO |
| Subnet | An IP network range (IPv4/IPv6). | L3_ADJACENT |
| VLAN | A Layer 2 broadcast domain. | HAS_INTERFACE |
| DNS Zone | A domain name space managed by DDI. | HAS_RECORD |
| Application | A business service or application. | DEPENDS_ON |
Sources: CLAUDE.md:50-55, backend/tests/workers/test_topology_tasks.py:165-185, backend/tests/engines/topology/test_rebuild_exit_criteria.py:205-235
Visualizing the Network Model
This diagram illustrates how the platform structures the connections between different network elements in the graph database.
Component Roles in Topology
The maintenance of the graph is an automated process handled by the background worker.
| Component | Role in Topology |
|---|---|
| Discovery Agent | Crawls devices using protocols like SNMP, SSH, LLDP, and CDP to find neighbors and IP information. |
| Topology Engine | Processes discovered data to "derive" connections (e.g., matching LLDP neighbors to specific interfaces). |
| Neo4j Projector | Converts the derived connections into "Cypher" commands (graph database language) to update the map. |
| Documentation Agent | Uses the graph data to generate Mermaid-formatted diagrams for the user. |
Sources: CLAUDE.md:44-55, backend/app/agents/documentation/agent.py:46-75, backend/tests/workers/test_topology_tasks.py:220-250
Summary
The Living Topology Graph is more than just a static map; it is a dynamic representation of your network infrastructure. By combining data from discovery scans, DDI providers, and cloud APIs into a single Neo4j graph, the platform provides the AI with the context it needs to diagnose faults like a human engineer would. Because the graph is projected from the Postgres system of record, it remains resilient, accurate, and easily auditable.