Diagram: Topology Data Model
Relevant source files
The following files were used as context for generating this wiki page:
Introduction
The AI Network Operations Platform acts as an automated assistant for network engineering teams, helping with discovery, troubleshooting, and configuration management across multi-vendor environments. The core of this platform is a "living topology map" that tracks how every device, interface, subnet, and application connects to everything else, providing a single source of truth for the network state.
Sources: CLAUDE.md:1-20, README.md:1-15
This topology model allows the platform to understand complex relationships, such as which devices sit in a specific subnet or how traffic flows between neighbors. By maintaining this map, the platform can automatically generate diagrams, analyze routing faults, and perform impact analysis for requested changes.
Sources: backend/app/agents/documentation/agent.py:1-25, backend/scripts/seed_smb_scenario.py:1-35
Platform Overview
The platform solves common operational challenges by providing a self-hosted, secure assistant that audits every action. It supports a wide range of vendors and protocols, including Cisco (IOS, NX-OS), Juniper, Arista, Palo Alto, and DDI backends like Infoblox and BlueCat.
Sources: CLAUDE.md:22-42, README.md:25-35
Design Philosophy
- Local-first & Self-hosted: All data and processing stay within your environment.
- Human Approval: Every change requested by the AI requires a human to review and approve it before execution.
- Visible Reasoning: Every decision made by the AI is explained and logged for audit purposes.
Sources: CLAUDE.md:44-55, README.md:5-15
Specialized Team Members (Agents)
The platform uses "specialized team members" called agents to handle specific tasks. When you ask a question, the platform routes it to the most appropriate expert:
- Discovery Agent: Scans the network to list what exists.
- Troubleshooting Agent: Diagnoses why a route or peer is missing.
- DDI Agent: Manages DNS records and DHCP scopes.
- Documentation Agent: Generates diagrams and runbooks.
Sources: CLAUDE.md:57-70, backend/app/agents/documentation/agent.py:46-65
Platform Architecture
The platform is composed of seven main components that work together to manage your network.
Components
- frontend: The operations console where you chat with the AI and view topology maps.
- api: The gateway that handles user sessions and coordinate between other components.
- worker: The background engine that runs discovery jobs, takes config backups, and captures packets without blocking your session.
- postgres: The main database (system of record) that stores device inventory and settings.
- neo4j: The living topology map that tracks connections between devices, subnets, and interfaces.
- redis: A temporary storage area used to coordinate tasks for the background worker.
- ollama: An optional component for running the AI "brain" (LLM) entirely on your local hardware.
Sources: README.md:17-25, deploy/docker/README.md:10-20
Multi-Vendor Connector System
The platform uses a standardized connector for each vendor. No matter whether you are talking to a Cisco router, a Juniper switch, or a BlueCat Address Manager, the platform normalizes the output into a consistent format before doing anything with it.
Sources: README.md:25-30, backend/scripts/seed_smb_scenario.py:40-60
Deployment Options
- Docker Compose: A single-server setup ideal for a lab environment or a small team.
- Kubernetes/Helm: A production-grade, multi-node deployment that is highly available and resilient.
Sources: README.md:37-45, deploy/docker/README.md:1-8
System Diagrams
Platform Connectivity
This diagram shows how users interact with the platform and what external systems the platform connects to.
The platform acts as a central hub connecting engineers to their multi-vendor infrastructure and AI models.
Sources: CLAUDE.md:22-42, README.md:17-35
Agent Routing Flow
When you send a request, the "Master Architect" decides which specialist should handle it.
Requests are routed to specialists; "read" actions happen immediately, while "write" actions wait for a human.
Sources: CLAUDE.md:57-70, backend/app/agents/documentation/agent.py:1-40
Change Approval Lifecycle
Every change follows a strict path from a draft to completion or rollback.
The approval workflow ensures no change happens without a human and a safety backup.
Sources: CLAUDE.md:1-15, README.md:5-15, backend/app/agents/documentation/agent.py:15-30
Topology Data Model
This is "what the platform knows about your network," representing how physical and logical components relate.
The topology map links physical devices to logical subnets, VLANs, and DNS records.
Sources: backend/tests/workers/test_topology_tasks.py:140-165, backend/scripts/seed_smb_scenario.py:65-150, backend/tests/engines/topology/test_rebuild_exit_criteria.py:80-120
Topology Field Definitions
| Entity | Description | Key Fields |
|---|---|---|
| Device | Physical or virtual hardware. | Hostname, Management IP, Vendor, Serial |
| Interface | Physical or logical port. | Name, Admin Status, Oper Status, Speed |
| Subnet | IP network segment. | CIDR Prefix (e.g. 10.0.0.0/24) |
| Route | Routing table entry. | Destination, Protocol (OSPF/BGP), Next Hop |
| Neighbor | Adjacent connected device. | Protocol (LLDP/CDP), Local Port, Remote Port |
| Sources: backend/scripts/seed_smb_scenario.py:65-150, backend/tests/workers/test_topology_tasks.py:60-120 |
Conclusion
The Topology Data Model is the foundational "map" the AI assistant uses to navigate your network. By combining physical connection data (LLDP/CDP) with logical layer-3 data (Routing/Subnets), the platform can provide accurate troubleshooting and documentation for complex, multi-vendor environments while maintaining strict human-in-the-loop security.
Sources: README.md:1-15, backend/app/agents/documentation/agent.py:46-65