> For the complete documentation index, see [llms.txt](https://docs.infraglide.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.infraglide.com/getting-started/architecture.md).

# Platform Architecture

This page explains how InfraGlide turns a visual canvas into live cloud infrastructure using Terraform, and how the major subsystems fit together across AWS, Azure, and GCP.

***

## Architectural Flow

```
Visual Canvas (React / Canvas state)
  → Property panel & container inheritance rules
  → real-time HCL / JSON generation (main.tf.json)
  → user clicks Deploy / Preview / Destroy
  → execution backend job queue
  → artifact store upload
  → Terraform CLI execution (credentials as env vars)
  → state + logs + resource tracking
  → optional drift check against live cloud APIs
```

***

## Canvas and Saved Configuration

The canvas is the authoring surface. Nodes and edges are stored on the pipeline row:

* `components` — resource and container nodes, including nested layout and configuration.
* `connections` — visual edges between nodes, later used for dependency mapping.

Only the **saved** pipeline is a deploy handoff. Unsaved UI state never reaches the Terraform generators.

Provider-specific forms and inheritance rules enrich node configuration before generation (region, subnet, resource group, and similar fields). Details live in the Visual Canvas documentation.

***

## Terraform Generation

InfraGlide generates **Terraform JSON** configurations for canvas pipelines.

* Output file: a single `main.tf.json` containing blocks such as `terraform`, `provider`, `variable`, `resource`, `data`, and optionally `module` or `import`.
* Generators emit structured configuration blocks that map directly to Terraform syntax.
* Resource addresses and interpolations use standard Terraform expressions inside JSON values (for example `"${aws_vpc.main.id}"`).

<figure><img src="/files/bGsYInQDdOU2wHzD7w9u" alt="Real-time Terraform Generation"><figcaption><p>Figure 2: Real-time Terraform HCL JSON Code Generation</p></figcaption></figure>

### Import Direction

You can **import** existing Terraform into the canvas:

* Client import accepts Terraform JSON and HCL (`.tf`).
* The Template Converter can also accept CloudFormation, ARM, and Google Deployment Manager templates and convert them into Terraform configurations.

Import parses HCL and provider templates to reconstruct the visual graph.

For deeper generator and provider-version details, see [Real-Time Code Generation](/terraform-iac-engine/code-generation.md) and [Provider & Plugin Management](/terraform-iac-engine/provider-versions.md).

***

## Multi-Cloud Providers

Each pipeline targets one provider. Org Admins can allow or block AWS, GCP, and Azure for the organization.

| Provider  | Typical Credential Material        | Injected Provider Environment Variables                                      |
| --------- | ---------------------------------- | ---------------------------------------------------------------------------- |
| **AWS**   | Access key pair or IAM Assume Role | `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, optional `AWS_SESSION_TOKEN`   |
| **GCP**   | Service Account JSON               | `GOOGLE_CREDENTIALS`                                                         |
| **Azure** | Service Principal                  | `ARM_CLIENT_ID`, `ARM_CLIENT_SECRET`, `ARM_TENANT_ID`, `ARM_SUBSCRIPTION_ID` |

Credentials are decrypted securely only at execution time and passed into the Terraform execution process. They are never written to disk or saved into `main.tf.json`.

Default provider plugin pins (selectable in the UI, overridable per pipeline) include:

* AWS provider `5.83.0` (Terraform CLI compatible `>=1.5.0`)
* GCP provider `6.0.0` or `7.39.0` (Terraform CLI compatible `>=1.5.0`)
* Azure provider `4.30.0` (Terraform CLI compatible `>=1.9.8`)

Pipeline versions also store a `terraformVersion` pin (default `1.9.8`).

***

## Execution Engine

Deployments run asynchronously in the background:

1. The platform validates permissions, pipeline locks, and (for destroy actions) the confirmation phrase.
2. Status updates to **Running**.
3. Background execution workers start the job asynchronously.
4. The client receives real-time log output and status updates via WebSockets.

<figure><img src="/files/GDHa3XfOoiQQj7hJoXAe" alt="Live Deployment Execution Logs"><figcaption><p>Figure 3: Real-Time Asynchronous Deployment Logs</p></figcaption></figure>

CLI execution stages use standard safety flags such as `-input=false`, `-no-color`, `-lock-timeout=60s`, and `-auto-approve` for apply/destroy runs.

Concurrency controls:

* Only one active deployment run per pipeline at a time.
* Lineage locks prevent multiple versions of the same pipeline from running concurrently.
* State lock timeout is set to 60 seconds.

***

## State and Artifacts

For canvas pipelines, Terraform state (`terraform.tfstate`) is maintained securely for each pipeline version.

Artifact storage preserves generated run artifacts such as:

* `main.tf.json`
* `.terraform.lock.hcl`

Migration landing-zone templates support remote backend state blocks for team collaboration.

***

## Logs and Observability

* **Live Logs**: Real-time WebSocket streaming outputs log lines as Terraform provisions or tears down infrastructure.
* **Historical Logs**: Completed run logs remain searchable under the **Executions** tab.
* **Redaction**: Terraform log output automatically redacts sensitive cloud provider credentials and secrets.

The Observability page surfaces deployment logs, visual topologies, and (for Org Admins) administrative audit trails.

<figure><img src="/files/bThrECEf5xNdFGbu4zrn" alt="Terraform Execution Engine Pipeline"><figcaption><p>Figure 4: Live Execution logs</p></figcaption></figure>

***

## Drift and Inventory

After resources are tracked, InfraGlide can:

* Discover live inventory through provider SDK / cache services (Deployed Resources).
* Compare saved desired configuration to live cloud state (Drift Detection).
* Optionally import selected inventory items into a new pipeline.

<figure><img src="/files/UZFx4RpEBsKFFVHkjNqT" alt="Real-Time Drift Detection Canvas"><figcaption><p>Figure 5: Real-Time Drift Detection &#x26; Inventory Reconciliation</p></figcaption></figure>

Drift is **not** computed by running `terraform plan`. It uses live describe/list APIs against stored desired configuration.

***

## Multi-Tenant Isolation

* Every API request runs under authentication and organization context.
* Credentials belong to a Sandbox. A user cannot run a pipeline against credentials outside their Sandbox access.
* Database rows rely on Organization and Sandbox context for multi-tenant isolation.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.infraglide.com/getting-started/architecture.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.