# shariatissh/ai-stack-ops architecture

> Architecture diagram of the GitHub repository shariatissh/ai-stack-ops, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/shariatissh/ai-stack-ops
- Repository: https://github.com/shariatissh/ai-stack-ops

## Overview

AiStackOps is an OpenStack administration copilot exposed through a safe CLI and an MCP server for AI agents. The main workflow is a user request entering either interface, being translated into an osctl operation, and interacting with OpenStack; mutations preview a plan unless explicitly confirmed. The README also documents setup/authentication, server diagnostics and lifecycle management, security-group auditing and changes, infrastructure backup/revert, and inventory for volumes, floating IPs, networks, and quotas. The implementation is largely concentrated in osctl.py; relationships beyond the shown call sites rely on README documentation.

Main entry points: [`osctl.py`](https://github.com/shariatissh/ai-stack-ops/blob/main/osctl.py) (osctl CLI), [`aistackops_mcp.py`](https://github.com/shariatissh/ai-stack-ops/blob/main/aistackops_mcp.py) (MCP Server)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["User Interfaces"]
  node_cli["osctl CLI<br/>[osctl.py]"]
  node_mcp["MCP Server<br/>[aistackops_mcp.py]"]
end

subgraph group_core["Operations Core"]
  node_setup["Setup and Auth<br/>[osctl.py]"]
  node_overview["Overview and Quotas<br/>[osctl.py]"]
  node_servers["Server Operations<br/>[osctl.py]"]
  node_diagnostics["Server Diagnostics<br/>[osctl.py]"]
  node_network_inventory["Network Inventory<br/>[osctl.py]"]
  node_volume_inventory["Volume Inventory<br/>[osctl.py]"]
end

subgraph group_security["Security and Recovery"]
  node_sg_management["Security Groups<br/>[osctl.py]"]
  node_sg_audit["Security Audit<br/>[osctl.py]"]
  node_safe_mutations["Preview and Confirm<br/>[osctl.py]"]
  node_backup["State Backup<br/>[osctl.py]"]
  node_revert["State Revert<br/>[osctl.py]"]
end

subgraph group_cloud["Cloud Access"]
  node_client["OpenStack Client<br/>[osctl.py]"]
  node_cloud_api["OpenStack Cloud"]
end

node_user(("Operator / AI"))

node_user -->|"runs commands"| node_cli
node_user -->|"sends requests"| node_mcp
node_cli -->|"configures access"| node_setup
node_cli -->|"requests summaries"| node_overview
node_cli -->|"requests operations"| node_servers
node_cli -->|"requests diagnosis"| node_diagnostics
node_cli -->|"requests inventory"| node_network_inventory
node_cli -->|"requests inventory"| node_volume_inventory
node_cli -->|"requests changes"| node_sg_management
node_cli -->|"requests audit"| node_sg_audit
node_cli -->|"requests backup"| node_backup
node_cli -->|"requests revert"| node_revert
node_mcp -->|"creates client"| node_client
node_mcp -->|"dispatches tools"| node_servers
node_mcp -->|"dispatches tools"| node_sg_management
node_mcp -->|"dispatches tools"| node_sg_audit
node_mcp -->|"dispatches tools"| node_diagnostics
node_mcp -->|"dispatches tools"| node_backup
node_mcp -->|"dispatches tools"| node_revert
node_setup -->|"loads credentials"| node_client
node_overview -.->|"queries cloud"| node_client
node_servers -.->|"queries cloud"| node_client
node_diagnostics -.->|"inspects state"| node_client
node_network_inventory -.->|"queries cloud"| node_client
node_volume_inventory -.->|"queries cloud"| node_client
node_sg_management -.->|"reads and changes"| node_client
node_sg_audit -.->|"checks rules"| node_client
node_safe_mutations -->|"gates actions"| node_servers
node_safe_mutations -->|"gates changes"| node_sg_management
node_backup -.->|"snapshots state"| node_client
node_revert -.->|"restores state"| node_client
node_client -->|"uses APIs"| node_cloud_api

click node_cli "https://github.com/shariatissh/ai-stack-ops/blob/main/osctl.py"
click node_mcp "https://github.com/shariatissh/ai-stack-ops/blob/main/aistackops_mcp.py"
click node_setup "https://github.com/shariatissh/ai-stack-ops/blob/main/osctl.py"
click node_overview "https://github.com/shariatissh/ai-stack-ops/blob/main/osctl.py"
click node_servers "https://github.com/shariatissh/ai-stack-ops/blob/main/osctl.py"
click node_diagnostics "https://github.com/shariatissh/ai-stack-ops/blob/main/osctl.py"
click node_network_inventory "https://github.com/shariatissh/ai-stack-ops/blob/main/osctl.py"
click node_volume_inventory "https://github.com/shariatissh/ai-stack-ops/blob/main/osctl.py"
click node_sg_management "https://github.com/shariatissh/ai-stack-ops/blob/main/osctl.py"
click node_sg_audit "https://github.com/shariatissh/ai-stack-ops/blob/main/osctl.py"
click node_safe_mutations "https://github.com/shariatissh/ai-stack-ops/blob/main/osctl.py"
click node_backup "https://github.com/shariatissh/ai-stack-ops/blob/main/osctl.py"
click node_revert "https://github.com/shariatissh/ai-stack-ops/blob/main/osctl.py"
click node_client "https://github.com/shariatissh/ai-stack-ops/blob/main/osctl.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cli,node_mcp toneBlue
class node_setup,node_overview,node_servers,node_diagnostics,node_network_inventory,node_volume_inventory toneAmber
class node_sg_management,node_sg_audit,node_safe_mutations,node_backup,node_revert toneMint
class node_client,node_cloud_api toneRose
class node_user toneIndigo
```

## Components

### User Interfaces

- [osctl CLI](https://github.com/shariatissh/ai-stack-ops/blob/main/osctl.py): `osctl.py`
- [MCP Server](https://github.com/shariatissh/ai-stack-ops/blob/main/aistackops_mcp.py): `aistackops_mcp.py`

### Operations Core

- [Setup and Auth](https://github.com/shariatissh/ai-stack-ops/blob/main/osctl.py): `osctl.py`
- [Overview and Quotas](https://github.com/shariatissh/ai-stack-ops/blob/main/osctl.py): `osctl.py`
- [Server Operations](https://github.com/shariatissh/ai-stack-ops/blob/main/osctl.py): `osctl.py`
- [Server Diagnostics](https://github.com/shariatissh/ai-stack-ops/blob/main/osctl.py): `osctl.py`
- [Network Inventory](https://github.com/shariatissh/ai-stack-ops/blob/main/osctl.py): `osctl.py`
- [Volume Inventory](https://github.com/shariatissh/ai-stack-ops/blob/main/osctl.py): `osctl.py`

### Security and Recovery

- [Security Groups](https://github.com/shariatissh/ai-stack-ops/blob/main/osctl.py): `osctl.py`
- [Security Audit](https://github.com/shariatissh/ai-stack-ops/blob/main/osctl.py): `osctl.py`
- [Preview and Confirm](https://github.com/shariatissh/ai-stack-ops/blob/main/osctl.py): `osctl.py`
- [State Backup](https://github.com/shariatissh/ai-stack-ops/blob/main/osctl.py): `osctl.py`
- [State Revert](https://github.com/shariatissh/ai-stack-ops/blob/main/osctl.py): `osctl.py`

### Cloud Access

- [OpenStack Client](https://github.com/shariatissh/ai-stack-ops/blob/main/osctl.py): `osctl.py`
- **OpenStack Cloud**

### Other components

- **Operator / AI**

## Connections

- Operator / AI → osctl CLI: runs commands (evidence: `README.md`)
- Operator / AI → MCP Server: sends requests (evidence: `README.md`)
- osctl CLI → Setup and Auth: configures access (evidence: `README.md`)
- osctl CLI → Overview and Quotas: requests summaries (evidence: `README.md`)
- osctl CLI → Server Operations: requests operations (evidence: `README.md`)
- osctl CLI → Server Diagnostics: requests diagnosis (evidence: `README.md`)
- osctl CLI → Network Inventory: requests inventory (evidence: `README.md`)
- osctl CLI → Volume Inventory: requests inventory (evidence: `README.md`)
- osctl CLI → Security Groups: requests changes (evidence: `README.md`)
- osctl CLI → Security Audit: requests audit (evidence: `README.md`)
- osctl CLI → State Backup: requests backup (evidence: `README.md`)
- osctl CLI → State Revert: requests revert (evidence: `README.md`)
- MCP Server → OpenStack Client: creates client (evidence: `aistackops_mcp.py`)
- MCP Server → Server Operations: dispatches tools (evidence: `aistackops_mcp.py`)
- MCP Server → Security Groups: dispatches tools (evidence: `aistackops_mcp.py`)
- MCP Server → Security Audit: dispatches tools (evidence: `README.md`)
- MCP Server → Server Diagnostics: dispatches tools (evidence: `README.md`)
- MCP Server → State Backup: dispatches tools (evidence: `README.md`)
- MCP Server → State Revert: dispatches tools (evidence: `README.md`)
- Setup and Auth → OpenStack Client: loads credentials (evidence: `osctl.py`)
- Overview and Quotas → OpenStack Client: queries cloud (evidence: `osctl.py`)
- Server Operations → OpenStack Client: queries cloud (evidence: `osctl.py`)
- Server Diagnostics → OpenStack Client: inspects state (evidence: `osctl.py`)
- Network Inventory → OpenStack Client: queries cloud (evidence: `osctl.py`)
- Volume Inventory → OpenStack Client: queries cloud (evidence: `osctl.py`)
- Security Groups → OpenStack Client: reads and changes (evidence: `osctl.py`)
- Security Audit → OpenStack Client: checks rules (evidence: `osctl.py`)
- Preview and Confirm → Server Operations: gates actions (evidence: `README.md`)
- Preview and Confirm → Security Groups: gates changes (evidence: `README.md`)
- State Backup → OpenStack Client: snapshots state (evidence: `osctl.py`)
- State Revert → OpenStack Client: restores state (evidence: `osctl.py`)
- OpenStack Client → OpenStack Cloud: uses APIs (evidence: `README.md`)