> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tensor9.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Architecture

> Understand the request path, operational path and state boundaries of Cloud Adapter.

Cloud Adapter is a runtime translation layer between software that speaks an origin cloud API and the native services selected for its target environment. The request path stays inside your environment. The local Tensor9 CLI configures and operates that runtime, but does not proxy application traffic.

<div className="cloud-adapter-architecture-frame">
  <Frame>
    <img className="block dark:hidden" src="https://mintcdn.com/tensor9/3qwgIru3kCfHriJC/images/diagrams/cloud-adapter-architecture-light.svg?fit=max&auto=format&n=3qwgIru3kCfHriJC&q=85&s=19d99212b327ef6ab8985dbf7b152894" alt="An application sends origin API requests through a Cloud Adapter service adapter to native target services. The Tensor9 CLI provides configuration outside the request path, and cluster deployments use a coordination store." width="1200" height="650" data-path="images/diagrams/cloud-adapter-architecture-light.svg" />

    <img className="hidden dark:block" src="https://mintcdn.com/tensor9/3qwgIru3kCfHriJC/images/diagrams/cloud-adapter-architecture-dark.svg?fit=max&auto=format&n=3qwgIru3kCfHriJC&q=85&s=4cdabc9105b0deb9c3775aac02d18370" alt="An application sends origin API requests through a Cloud Adapter service adapter to native target services. The Tensor9 CLI provides configuration outside the request path, and cluster deployments use a coordination store." width="1200" height="650" data-path="images/diagrams/cloud-adapter-architecture-dark.svg" />
  </Frame>
</div>

## The request path

Each request crosses three adapter stages:

1. **API endpoint.** Your existing SDK, CLI or infrastructure tool sends an origin-shaped request to the configured Cloud Adapter endpoint.
2. **Service adapter.** The selected origin-to-backend mapping interprets the request and translates its supported behavior.
3. **Target client.** Cloud Adapter calls the native target service using the backend identity configured for that mapping.

The response follows the reverse path. Cloud Adapter translates the target result into the origin API's response shape. When emitted, [diagnostic response headers](/cloud-adapter/debugging/response-headers) can supply correlation identifiers or narrowly defined request-effect evidence.

A cloud adapter is therefore composed of service adapters. Each service adapter owns one origin-service-to-backend mapping; the cloud adapter gives those mappings one operating boundary for a particular origin-to-target direction.

## The operations path

The local Tensor9 CLI reads the installation's configuration, validates changes and coordinates setup and updates. Configuration has two scopes:

* **Cloud adapter configuration** defines settings shared by the installation, such as its origin and target clouds, networking and deployment shape.
* **Service adapter configuration** selects a backend and supplies the settings needed for one service mapping.

Both scopes feed the runtime, but neither sits in the application request path. This separation lets the CLI stop after an operation while the adapters continue to serve traffic. See [Configuration](/cloud-adapter/configuration/overview) and [Operations](/cloud-adapter/operations/overview).

## Identity and trust boundaries

Cloud Adapter crosses distinct security boundaries. Treat them separately:

| Boundary                       | Governs                                                            |
| ------------------------------ | ------------------------------------------------------------------ |
| Application to adapter         | Which callers can reach and use the origin API endpoint.           |
| Adapter to target service      | Which native operations the backend identity can perform.          |
| Operator to target environment | Which infrastructure and lifecycle changes the local CLI can make. |

An origin-shaped request does not inherit permission to the target service. Likewise, a target-cloud credential does not decide who may call the adapter. Apply least privilege independently at each boundary and keep provisioning credentials separate from runtime credentials.

## Where state lives

Application data belongs to the selected target service. For example, an S3-to-Cloud Storage adapter stores objects in Cloud Storage; it does not keep a second object copy inside Cloud Adapter.

Cluster deployments also use a PostgreSQL coordination store. That store coordinates adapter processes; it is separate from the application data held by target services. Inventory, back up and recover those stores according to their different roles.

Configuration is another durable input. Keep it under review and change control, because changing a backend can change data ownership and migration requirements even when the file remains syntactically valid.

## How deployment changes the topology

The request translation remains the same across deployment choices. What changes is how the runtime is arranged:

| Deployment                                               | Runtime topology                                                  | Additional infrastructure                                           |
| -------------------------------------------------------- | ----------------------------------------------------------------- | ------------------------------------------------------------------- |
| [Single binary](/cloud-adapter/deployment/single-binary) | One service adapter process and one endpoint.                     | No shared coordination store.                                       |
| [Cluster](/cloud-adapter/deployment/cluster)             | Multiple adapter processes behind an application-facing endpoint. | Shared PostgreSQL coordination, load balancing and rollout policy.  |
| [Provisioned](/cloud-adapter/deployment/provisioned)     | The same adapter runtime, installed by the local Tensor9 CLI.     | Target-cloud compute, networking, identity and lifecycle resources. |

Adding processes improves process availability or throughput; it does not expand a service mapping's operation coverage. Review the selected service adapter's reference page before choosing a deployment shape.

## Observe a request

Use [`tensor9 explain`](/cloud-adapter/debugging/explain) to inspect how a request maps to its target behavior without sending it through the full deployment. During live diagnosis, combine that explanation with the adapter's [response headers](/cloud-adapter/debugging/response-headers), runtime logs and the resulting target-service state.