StackAI Architecture & End-to-End Workflow
This document specifies the logical architecture, component boundaries, execution lifecycles, and security controls governing StackAI in StackConsole CMP.
StackAI is the conversational operations assistant embedded inside the customer cloud console. It enables end customers to manage cloud infrastructure using natural language without memorizing API syntax, command parameters, or provider-specific identifiers.
StackAI is the conversational intelligence layer. Internal OpenAPI/tools expose controlled capabilities. CMP is the authoritative application, authorization, tenant, and orchestration layer. CloudStack is the underlying infrastructure provider. StackAI must not bypass CMP to directly operate CloudStack.
1. StackAI Logical Architecture
The following diagram illustrates how a natural-language request flows from the end user down to the underlying infrastructure, and how responses travel back up through the same layers.
END USER
│
│ Natural-language request
▼
┌─────────────────────┐
│ StackAI UI │
│ Customer Console │
└──────────┬──────────┘
│
▼
┌─────────────────────┐
│ StackAI Agent / │
│ AI Orchestrator │
└──────────┬──────────┘
│
Intent / Tool Selection
│
▼
┌─────────────────────┐
│ Internal OpenAPI / │
│ Tool Definitions │
└──────────┬──────────┘
│
API invocation
│
▼
┌─────────────────────┐
│ CMP API │
│ StackConsole CMP │
└──────────┬──────────┘
│
Authentication /
Authorization /
Tenant Context
│
▼
┌─────────────────────┐
│ CMP Orchestrator / │
│ Cloud Integration │
└──────────┬──────────┘
│
Provider API
│
▼
┌─────────────────────┐
│ CloudStack API │
│ Apache CloudStack │
└──────────┬──────────┘
│
▼
┌─────────────────────┐
│ CloudStack Managed │
│ Infrastructure │
│ │
│ Zones / Pods / VMs │
│ Networks / Storage │
└─────────────────────┘
The response flows symmetrically in reverse:
Cloud Infrastructure
↓
CloudStack API
↓
CMP Integration
↓
CMP API
↓
Internal OpenAPI / Tool Layer
↓
StackAI Agent
↓
StackAI UI
↓
End User
This diagram describes a logical architecture: component roles, trust boundaries, and execution contracts. It does not dictate that each box is deployed as an independent physical microservice. Certain components (such as CMP API and CMP Orchestrator Integration) may reside within the same backend application tier while maintaining strict internal abstraction boundaries.
2. Component Responsibilities
Every layer in the architecture has a single, well-defined operational responsibility:
| Layer | Responsibility |
|---|---|
| End User | Expresses intent using natural language (e.g., "Show my virtual machines", "Create a 4 CPU VM"). |
| StackAI UI | Captures user requests, provides conversational history, renders confirmation prompts, and displays structured status cards and execution outcomes. |
| StackAI Agent / AI Orchestrator | Understands intent, determines required actions, selects appropriate tools/APIs from available tool schemas, maintains dialogue context, and coordinates user confirmations. |
| Internal OpenAPI / Tool Layer | Defines operations available to StackAI in a structured, machine-callable contract (OpenAPI / JSON schemas). Validates tool input parameters before dispatching. |
| CMP API | Provides the controlled application and API boundary for all customer-facing platform operations. |
| CMP Authorization / Tenant Context | Enforces identity, role-based access control (RBAC), tenant isolation, account/project ownership, resource quotas, and policy rules. |
| CMP Orchestrator | Translates high-level CMP business operations into specific infrastructure-provider operations and API calls. |
| CloudStack API | Performs actual infrastructure commands against Apache CloudStack (e.g., compute allocation, networking, volume management). |
| CloudStack Infrastructure | Executes requested physical or virtual hypervisor, network, and storage changes, returning raw provider status. |
StackAI must not directly call CloudStack APIs. StackAI interacts exclusively through the controlled CMP API abstraction layer.
3. End-to-End Request Lifecycle: Read Operation Flow
To understand the complete lifecycle, consider a concrete read operation:
User: "Show me all my virtual machines."
The request traverses ten distinct phases:
Step 1 — User request
The customer enters a plain-language prompt into the StackAI chat box:
Show me all my virtual machines.
Step 2 — StackAI receives the request
The StackAI UI captures the text and binds it to the current customer session context.
The customer does not need to know:
- Backend API endpoints or paths
- Apache CloudStack commands or syntax
- Infrastructure credentials or secret tokens
- Internal hypervisor, zone, pod, or cluster UUIDs
Step 3 — AI interprets the intent
The StackAI Agent parses the natural-language input and identifies the user's intent: querying the account's virtual machines.
The agent selects the appropriate conceptual tool:
list_virtual_machines
Note: list_virtual_machines is a conceptual tool identifier. The underlying implementation maps this to an internal OpenAPI endpoint schema.
Step 4 — Internal OpenAPI / tool invocation
Instead of constructing an ad-hoc query or attempting direct infrastructure access, the AI invokes the controlled internal tool schema.
Conceptual dispatch:
StackAI Agent
│
│ Invoke tool
▼
Internal OpenAPI / Tool Layer
│
│ list virtual machines
▼
CMP API
Conceptual machine-callable payload:
{
"operation": "list_virtual_machines",
"tenant_context": "<authenticated-customer-context>"
}
(Note: Conceptual payload representation. The exact production schema is managed by the internal tool definitions).
Step 5 — CMP authorization and tenant context validation
The CMP API receives the request and immediately evaluates:
- Authenticated identity: Is the user session valid?
- Customer/Tenant scope: Which organization or account does this user belong to?
- Project context: Which cloud project is currently active?
- RBAC permissions: Does the user possess read permissions for compute instances?
- Resource scope: Filter queries exclusively to instances owned by this tenant/project.
The AI model is never trusted to determine or override authorization. All permission checks and tenant scoping are strictly enforced by CMP server-side code.
Step 6 — CMP calls CloudStack
Once authorized, the CMP Orchestrator resolves the tenant's assigned zone and infrastructure backend, translating the internal request into the appropriate CloudStack API operation:
CMP Orchestrator
│
│ CloudStack API request (e.g. listVirtualMachines)
▼
Apache CloudStack API
Conceptually, this corresponds to CloudStack's listVirtualMachines command, scoped to the account or domain mapped to that tenant.
Step 7 — CloudStack returns the result
CloudStack queries its database and hypervisor agents, returning raw infrastructure data (instance IDs, state, hypervisor attributes, NIC allocations, and storage mappings) to the CMP Orchestrator.
Step 8 — CMP normalizes the response
The CMP Orchestrator strips provider-specific hypervisor internals and normalizes the data into standard CMP platform entities:
- Internal CloudStack IDs are mapped to customer-visible identifiers.
- Provider state codes are converted to standard platform states (
Running,Stopped,Starting). - Compute and memory attributes are formatted according to the customer's service package.
This normalization keeps StackAI completely decoupled from CloudStack-specific schemas.
Step 9 — Result returned to StackAI
The normalized structured JSON response is delivered back through the internal OpenAPI/tool layer to the StackAI Agent.
Step 10 — AI generates the user response
The StackAI Agent transforms the structured result into a clear, natural-language response with visual summary cards:
You have 3 virtual machines:
1. web-server-01 — Running (2 vCPU · 4 GB RAM · 50 GB Disk)
2. database-01 — Running (4 vCPU · 8 GB RAM · 100 GB Disk)
3. test-vm-01 — Stopped (1 vCPU · 2 GB RAM · 20 GB Disk)
The UI displays the text alongside actionable instance cards in the chat window.
4. Workflow for a Mutating Operation
Mutating operations alter infrastructure state, consume billing quota, or incur hourly charges. They require stricter parameter validation and mandatory user confirmation.
Consider the request:
User: "Create a virtual machine with 4 vCPUs and 8 GB RAM."
Mutating request execution flow
User: "Create a VM with 4 vCPUs and 8 GB RAM"
│
▼
StackAI UI
│
▼
StackAI Intent Detection
│
▼
Parameter Collection & Clarification
(Queries for OS, network, disk, region)
│
▼
Confirmation Preview Rendered
(User clicks or replies "Yes / Proceed")
│
▼
Tool Selection & Schema Validation
│
▼
Internal OpenAPI Contract
│
▼
CMP API
│
▼
Authorization, Tenant & Quota Validation
│
▼
CMP CloudStack Integration Layer
│
▼
CloudStack API (deployVirtualMachine)
│
▼
CloudStack Infrastructure Provisioning
│
▼
CloudStack Async Job Completion
│
▼
CMP Normalized Status
│
▼
StackAI Agent Completion
│
▼
User: Confirmation Card & Details
Read vs Mutating Operations
To prevent accidental changes and ensure financial safety, the system divides operations into two distinct classes:
| Class | Characteristics | Examples | Safety Controls |
|---|---|---|---|
| Read Operations | Non-destructive, idempotent, zero billing impact, safe to execute immediately. | list VMs, show VM details, list networks, show storage, check resource status, show billing summary | Tenant isolation, RBAC validation. |
| Mutating Operations | State-altering, quota-consuming, potentially destructive or billable. | create VM, start VM, stop VM, reboot VM, create snapshot, resize volume, delete resource | Parameter validation, quota pre-checks, mandatory interactive confirmation preview, audit logging. |
StackAI will never execute a mutating or destructive operation on the first prompt without user confirmation. The agent constructs a preview detailing the target resource, specifications, and potential billing impact, awaiting an explicit confirmation (yes, proceed, or confirm) before calling the CMP API.
5. Security and Trust Boundaries
The StackAI architecture is engineered around the principle of least trust between conversational models and infrastructure.
AI is not the authorization authority
The Large Language Model (LLM) determines semantic intent and chooses candidate tools. However, the AI model has zero authority to grant permissions, bypass quotas, or override access controls.
Authorization is strictly enforced by CMP server-side interceptors:
- If a user asks to delete a VM belonging to another tenant, the AI may formulate a request, but the CMP API rejects it with an HTTP
403 Forbidden/404 Not Found. - If an account has exceeded its CPU quota, CMP blocks instance creation regardless of AI prompt framing.
Direct vs Mediated Access
INCORRECT (Forbidden Pattern)
┌──────────────┐ Bypasses CMP security, tenant ┌──────────────────┐
│ StackAI │ ──────────────────────────────────────────> │ CloudStack API │
└──────────────┘ isolation & audit records └──────────────────┘
CORRECT (Enforced Architecture)
┌──────────────┐
│ StackAI │
└──────┬───────┘
│ Controlled tool schema
▼
┌───────────────────────────────┐
│ Internal OpenAPI / Tool Layer │
└──────┬────────────────────────┘
│ Authenticated customer session
▼
┌───────────────────────────────┐
│ CMP API │ ◄── Enforces AuthN, RBAC, Tenancy, Quotas & Auditing
└──────┬────────────────────────┘
│ Provider abstraction
▼
┌───────────────────────────────┐
│ CMP Orchestrator │
└──────┬────────────────────────┘
│ Infrastructure credentials
▼
┌───────────────────────────────┐
│ CloudStack API │
└──────┬────────────────────────┘
│ Hypervisor commands
▼
┌───────────────────────────────┐
│ Cloud Infrastructure │
└───────────────────────────────┘
Why the CMP Abstraction Layer Exists
- Authentication & Identity Assertion: Validates that the request originates from an active, verified customer session.
- Tenant Isolation: Enforces multi-tenancy at the database and API layer, preventing cross-tenant leakage.
- Policy & Quota Enforcement: Validates project-level and account-level resource limits before touching infrastructure.
- End-to-End Auditability: Produces an immutable log connecting the user's natural-language action to the backend infrastructure change.
- Credential Encapsulation: CloudStack administrative API keys and secret tokens remain strictly within CMP backend storage and are never exposed to the AI model or client browser.
- API Normalization: Shields the AI from provider-specific XML/JSON nuances and error structures.
- Centralized Business Rules: Applies billing cycles, discount codes, and package restrictions uniformly across both UI and AI channels.
- Rate Limiting & Abuse Prevention: Protects orchestrator management servers from prompt injection loops or rapid-fire API hammering.
- Multi-Orchestrator Support: Allows the platform to route requests to different infrastructure backends without changing the conversational model.
6. Multi-Orchestrator Architecture
While Apache CloudStack is the primary cloud orchestrator documented, StackConsole CMP is built as an abstraction platform capable of orchestrating multiple infrastructure backends.
StackAI
│
▼
Internal OpenAPI
│
▼
CMP API
│
┌───────────────────┼───────────────────┐
│ │ │
▼ ▼ ▼
CMP CloudStack CMP OpenStack CMP VMware
Integration Integration Integration
│ │ │
▼ ▼ ▼
CloudStack API OpenStack API vCenter API
│ │ │
▼ ▼ ▼
CloudStack OpenStack VMware
Infrastructure Infrastructure Infrastructure
Abstraction Invariant
StackAI operates against unified CMP capabilities, while CMP owns provider-specific orchestration.
When support for additional orchestrators (such as OpenStack, VMware, or CEPH) is activated:
- The StackAI agent continues using the same internal OpenAPI operations (e.g.,
list_virtual_machines,create_virtual_machine). - The CMP routing layer detects the zone or project orchestrator type and dispatches the task to the appropriate driver.
- StackAI never requires prompt retraining or schema alterations when infrastructure providers change.
7. Authentication and Identity Flow
Identity flows securely across system boundaries without exposing infrastructure credentials:
User Login (SSO / Local Auth)
│
▼
Customer Console Session (Session Cookie / JWT)
│
▼
StackAI Interface (Inherits Authenticated Web Session)
│
▼
Internal Tool Request (Carries Authenticated CMP Tenant Context)
│
▼
CMP API (Validates Session, Tenant ID, Project ID, Role)
│
▼
CMP Orchestrator (Fetches Stored Provider Credentials)
│
▼
CloudStack API (Signed API Call Using CMP Stored Secret Keys)
Identity Rules
- Inherited Session: StackAI runs within the authenticated customer cloud console. End customers do not log in separately to StackAI.
- No End-User CloudStack Accounts: End customers are not provisioned direct administrative accounts inside CloudStack. All operations are mediated by CMP system credentials scoped to tenant domains/accounts.
- Session Revocation: If a customer's console session expires or is terminated, subsequent StackAI tool calls immediately fail with
401 Unauthorized. - Token Mechanisms: Specific token formats (such as JWT claims, OAuth2 bearer tokens, or internal session cookies) are implementation-specific and deployment-dependent.
8. Audit and Observability Flow
For compliance, troubleshooting, and administrative visibility, StackAI requests must be traceable across every architectural tier:
User Request ("Start my web-server VM")
│
▼
[StackAI Request ID] (Tracks conversational turn and user prompt)
│
▼
[Tool Invocation ID] (Tracks selected tool, parameters, and confirmation state)
│
▼
[CMP Request ID] (Tracks API authorization, tenant scope, and validation)
│
▼
[CloudStack Job ID] (Tracks orchestrator async job and hypervisor execution)
Core Audit Questions
Comprehensive logging enables administrators to answer the following nine questions for any action:
- Who requested the operation? (User ID, email, IP address)
- Which tenant initiated it? (Tenant ID, Account ID, Project ID)
- What natural-language prompt was entered? (Original user string)
- Which tool was selected by the AI? (Tool identifier and validated arguments)
- Which CMP API was invoked? (Endpoint, HTTP method, timestamp)
- Which infrastructure operation was executed? (CloudStack API command and target resource UUID)
- What was the result? (HTTP status, resource state, error codes)
- When did the operation execute? (Start timestamp, duration, completion timestamp)
- Did the operation succeed or fail? (Outcome classification and error message)
The multi-tier correlation model above represents the recommended target observability architecture. In current deployments, conversational logs in StackAI and infrastructure logs in CMP/CloudStack may reside in distinct subsystems linked by user and tenant timestamps.
9. Error Handling Flow
When an infrastructure operation fails, the error must propagate safely back to the user without exposing sensitive system internals.
CloudStack Infrastructure Error
↓
CloudStack API (Raw Exception / Error Code)
↓
CMP Orchestrator Integration (Intercepts provider failure)
↓
CMP API (Translates to normalized error model)
↓
Internal Tool Layer (Returns structured failure response)
↓
StackAI Agent (Formulates plain-language explanation)
↓
StackAI UI (Displays user-friendly message & remediation advice)
↓
End User
Provider Error Normalization
Raw CloudStack exceptions contain internal class names, database constraints, and cluster host details that are neither useful nor safe for end customers. CMP normalizes these into actionable business errors:
CloudStack Provider Error:
InsufficientServerCapacityException: Unable to create a deployment for VM[User|i-2-45-VM] scope [Zone:1]
↓ CMP Normalization Layer
CMP Normalized API Response:
{
"status": "error",
"code": "INSUFFICIENT_ZONE_CAPACITY",
"message": "Unable to provision virtual machine because sufficient compute capacity is currently unavailable in the selected zone."
}
↓ StackAI Conversational Formatting
StackAI User Response:
"I couldn't create the virtual machine because there is currently insufficient compute capacity in this region. Please try a different size or select another region."
Error Handling Rules
- No Stack Traces: Never output Java stack traces or internal database errors to end users.
- Actionable Remediation: When a request fails due to quotas or permissions, StackAI directs the customer to contact their account administrator or request a quota increase.
- No Autonomous Retries: If a mutating operation fails, StackAI does not loop or retry automatically, preventing accidental double-billing or cascading infrastructure load.
10. Sequence Diagrams
Read Operation Sequence Diagram
Mutating Operation Sequence Diagram
11. Architecture Principles
Twelve core architectural principles govern StackAI's implementation and evolution:
- Natural language is the user interface: Users describe desired outcomes in plain English; the platform handles complexity.
- StackAI does not directly access infrastructure APIs: All operations flow through CMP.
- Internal OpenAPI/tool definitions provide controlled AI capabilities: The AI model can only execute pre-defined, strictly typed tools.
- CMP is the authorization and orchestration boundary: Security, tenant isolation, and billing policies live outside the AI.
- CloudStack remains an infrastructure provider behind CMP: CloudStack knows nothing about StackAI; it only responds to CMP.
- Tenant and customer permissions are enforced outside the AI model: The AI cannot escalate permissions or bypass access controls.
- Provider-specific implementation details remain inside CMP integrations: CloudStack UUIDs and XML schemas do not leak into AI prompts.
- AI must only use explicitly exposed and allowed tools: Unregistered actions cannot be hallucinated or executed.
- Mutating operations require appropriate validation and confirmation: Destructive or billable actions always require user sign-off.
- Operations must be auditable and observable end-to-end: Every action links the human prompt to the infrastructure change.
- Provider failures must be normalized before presentation: Technical exceptions are converted to actionable plain language.
- The architecture supports additional infrastructure providers without redesigning StackAI: Adding OpenStack, VMware, or Kubernetes requires no changes to StackAI's conversational models.
12. What StackAI Knows vs What CMP Knows
To maintain clean separation of concerns, StackAI and CMP hold distinctly different responsibilities and state:
| Concern | StackAI | CMP |
|---|---|---|
| Natural-language intent | Yes — Parses user wording and detects goals | No — Operates on structured API endpoints |
| Conversation context & history | Yes — Maintains dialogue thread and parameters | No — Stateless API requests |
| Tool selection | Yes — Chooses which operation satisfies the prompt | No — Exposes endpoints; accepts or rejects calls |
| Tool schema | Uses — Formats calls according to schema contracts | Defines/Exposes — Publishes OpenAPI contracts |
| Customer authorization | Must respect — Relies on CMP validation | Enforces — Evaluates RBAC, tenant IDs, and tokens |
| Tenant isolation | Must respect — Operates within current session | Enforces — Scopes database records and queries |
| Business & pricing rules | May understand — Explains prices to users | Enforces — Computes billing, deductions, and rate cards |
| Provider-specific APIs | No — Blind to CloudStack commands | Yes — Translates CMP requests into CloudStack calls |
| CloudStack credentials | No — Never receives infrastructure secret keys | Yes — Securely stores and uses API keys |
| Infrastructure orchestration | No — Does not coordinate hypervisors or storage | Yes — Handles provisioning, tasks, and state sync |
| Provider abstraction | No — Consumes generic resource models | Yes — Abstracts CloudStack, OpenStack, CEPH, etc. |
| Audit & compliance tracking | Initiates context — Logs user prompt and turn | Owns platform enforcement — Commits immutable logs |
13. Example: One User Request Across the Entire Stack
Here is a complete walk-through of an everyday operational request:
User: "Start my web-server VM."
1. User enters request
↓
2. StackAI identifies "start VM" intent
↓
3. StackAI selects the approved VM-start tool (start_virtual_machine)
↓
4. Internal OpenAPI validates the tool contract and arguments
↓
5. CMP API receives the authorized request with tenant session context
↓
6. CMP validates customer identity, tenant scope, and VM ownership
↓
7. CMP identifies the target CloudStack zone and cluster
↓
8. CMP calls CloudStack API (startVirtualMachine&id=...)
↓
9. CloudStack instructs the hypervisor host to start the VM
↓
10. CloudStack returns async success result to CMP
↓
11. CMP normalizes result into standard instance state (State: "Running")
↓
12. StackAI receives structured success confirmation
↓
13. StackAI explains result to user and renders an updated instance card
Final User-Facing Response
I have started web-server-01. It is now up and running.
┌────────────────────────────────────────────────────────┐
│ web-server-01 ● Running │
│ Project: Production │
│ IP: 192.0.2.45 │
│ Specs: 4 vCPU · 8 GB RAM · 100 GB Disk │
└────────────────────────────────────────────────────────┘
Related Documentation
- StackAI Overview — High-level overview and admin onboarding
- StackAI User Guide — Complete tutorial and end-user operational workflows
- Production Requirements — OpenAI billing and API key setup
- CloudStack Orchestrator Setup — Configuring the underlying CloudStack environment
- Platform APIs — REST API conventions and token management in CMP