Change Approval Workflow
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 assistant designed for network engineering teams to manage infrastructure through plain English requests. It solves the risk of automated errors by acting as a "human-in-the-loop" system where every network modification requires explicit approval from a second engineer before execution.
The platform supports a wide array of vendors and protocols, including Cisco (IOS, IOS-XE, NX-OS), Juniper JunOS, Arista EOS, Palo Alto PAN-OS, Fortinet FortiOS, F5 BIG-IP, and DDI providers like BlueCat and Infoblox. The design philosophy emphasizes local-first security and total transparency—every AI decision is explained, audited, and logged.
Specialized Team Members (Agents)
The platform uses "agents," which you can think of as specialized team members that the platform routes your questions to:
- Master Architect: The supervisor that directs your request to the right specialist.
- Discovery Agent: Specializes in finding devices and mapping the network.
- Troubleshooting Agent: Diagnoses routing, BGP, OSPF, and connectivity issues.
- DDI Agent: Manages DNS, DHCP, and IP addresses.
- Configuration Agent: Handles device config backups and compliance.
- Security Agent: Audits firewall policies and proposes security fixes.
Sources: README.md, CLAUDE.md, backend/app/agents/security/agent.py:44-55
Architecture
The platform consists of seven core components working together to manage your network:
- frontend: The web console where you chat with the AI, view the topology, and approve changes.
- api: The central brain that handles security, user sessions, and coordinates between the UI and background tasks.
- worker: The background engine that runs discovery jobs, takes config backups, and captures packets without blocking your session.
- postgres: The primary database (system of record) that stores device info, user accounts, and logs.
- neo4j: A living topology map that tracks how every device, interface, subnet, and DNS zone connects to everything else.
- redis: A high-speed messenger used to queue jobs for the worker and store temporary data.
- ollama: A local engine that runs the AI models (LLMs) on your own hardware so no data leaves your network.
Multi-Vendor Plugin System
The platform uses a standardized connector for each vendor. Whether you are interacting with a Cisco router, a Juniper switch, or a BlueCat Address Manager, the platform normalizes the output into a consistent format before processing it. This ensures that the AI can reason about the network regardless of the underlying hardware vendor.
Sources: README.md, deploy/docker/README.md
Deployment Options
- Docker Compose: A single-server setup ideal for labs, testing, or small teams.
- Kubernetes/Helm: A production-ready, multi-node deployment that is highly available and resilient.
Sources: README.md, deploy/docker/README.md, deploy/kubernetes/netops/Chart.yaml
Change Approval Workflow
In this platform, no AI agent can change a device configuration or a DNS record directly. Instead, when an agent determines a change is needed, it drafts a Change Request (CR). This request must be reviewed and approved by a human engineer.
The Lifecycle of a Change
- Draft: The agent creates a plan for the change (e.g., adding a DNS record or tightening a firewall rule).
- Pending Approval: The change is visible in the "Changes" queue in the web console.
- Approved: A second engineer (not the one who requested it) reviews and approves the change.
- Executing: The Automation Agent takes the approved plan and applies it to the network.
- Completed/Failed/Rolled Back: The platform logs the result. If a change fails, it can be rolled back to the previous state.
Sources: backend/app/models/change_requests.py:16-25, frontend/src/pages/ChangesPage.tsx:14-25
Four-Eyes Principle
To prevent unauthorized or accidental changes, the system enforces "four-eyes" security. If a change is marked as requiring four-eyes approval, the engineer who requested the change cannot be the one to approve it. This ensures at least two people (the requester and the approver) are involved in every production change.
Sources: backend/app/agents/framework/approval.py:15-30, frontend/src/pages/ChangesPage.tsx:135-145
Diagrams
System Overview
This diagram shows how users interact with the platform and what external systems the platform manages.
The platform acts as the central hub connecting engineers to multi-vendor infrastructure.
Agent Routing and Approval Gate
This shows how a user's request moves from a plain-English question to either a direct answer or a gated change.
Read-only requests (like "Show me the routing table") happen immediately, while write requests (like "Add a DNS record") are diverted to the approval gate.
Change Approval Flow
The full lifecycle of a network change within the platform.
Every change is tracked from initial draft through to verified completion or recovery.
Sources: backend/app/models/change_requests.py, backend/app/agents/framework/approval.py, CLAUDE.md
Data Models
Change Request States
| State | Description |
|---|---|
draft | Initial creation, not yet submitted for review. |
pending_approval | Waiting for a second engineer to sign off. |
approved | Authorized and ready for the automation engine. |
executing | Currently being applied to the network devices. |
completed | Change successfully applied and verified. |
failed | Execution encountered an error. |
rolled_back | Change failed and the device was restored to its previous state. |
Sources: backend/app/models/change_requests.py:16-25, frontend/src/pages/ChangesPage.tsx:43-51
Change Request Fields
| Field | Type | Description |
|---|---|---|
id | UUID | Unique identifier for the change. |
kind | Enum | The type of change (e.g., config for devices, ddi for DNS). |
state | Enum | The current status in the workflow. |
payload | JSON | The technical details of the change (config lines, records). |
target_refs | JSON | List of specific devices or records being touched. |
four_eyes_required | Boolean | Whether a second person must approve the change. |
Sources: backend/app/models/change_requests.py:30-65
Summary
The Change Approval Workflow is the safety net of the AI Network Operations Platform. It ensures that while the AI can intelligently propose complex network modifications across diverse vendors like Cisco and Juniper, a human engineer always maintains final authority. By enforcing the four-eyes principle and maintaining a clear audit trail of every draft, approval, and execution, the platform provides the agility of automation without sacrificing the stability of the production network.