# Architecture

Depending on your chosen cloud provider and type of deployment, there can be different possible architectural setups to deploy CARTO Self-Hosted as illustrated below.

{% tabs %}
{% tab title="Google Cloud" %}
**Single Virtual Machine Deployment**

<figure><img src="https://3029946802-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FybPdpmLltPkzGFvz7m8A%2Fuploads%2F6cIuLvkZDhrxSLgO2Bb5%2FSelf-Hosted%20AT.png?alt=media&#x26;token=1f5cdec4-8f99-4dca-b1f5-bd4af592083c" alt=""><figcaption></figcaption></figure>

**Orchestrated container deployment**

<figure><img src="https://3029946802-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FybPdpmLltPkzGFvz7m8A%2Fuploads%2FIzOqYkZWUllgH1isbFQw%2FSelf-Hosted%20AT%20(6).png?alt=media&#x26;token=ab4c7cbd-55cc-446f-b67d-b4c68aeb04d0" alt=""><figcaption></figcaption></figure>
{% endtab %}

{% tab title="Amazon Web Services" %}
**Single Virtual Machine Deployment**

<figure><img src="https://3029946802-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FybPdpmLltPkzGFvz7m8A%2Fuploads%2FWgJ9YI2gZtoXd0hJLUpo%2FSelf-Hosted%20AT%20(1).png?alt=media&#x26;token=e030655d-c847-4421-99a9-76704d6e747c" alt=""><figcaption></figcaption></figure>

**Orchestrated container deployment**

<figure><img src="https://3029946802-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FybPdpmLltPkzGFvz7m8A%2Fuploads%2FwyjzqahtNI4950zP6qDi%2FSelf-Hosted%20AT%20(4).png?alt=media&#x26;token=3475e205-477f-4b57-ad07-f620f1ba9519" alt=""><figcaption></figcaption></figure>
{% endtab %}

{% tab title="Microsoft Azure" %}
**Single Virtual Machine Deployment**

<figure><img src="https://3029946802-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FybPdpmLltPkzGFvz7m8A%2Fuploads%2ForvyrEB1OaZ7WQVZpstT%2FSelf-Hosted%20AT%20(2).png?alt=media&#x26;token=46377472-52fa-4f7b-887e-ef0d9e3dc613" alt=""><figcaption></figcaption></figure>

**Orchestrated container deployment**

<figure><img src="https://3029946802-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FybPdpmLltPkzGFvz7m8A%2Fuploads%2FdUF2i0Raj1yH8NXz9m7u%2FSelf-Hosted%20AT%20(3).png?alt=media&#x26;token=84aa3368-6aaf-47fe-8a06-a26158f04db0" alt=""><figcaption></figcaption></figure>
{% endtab %}
{% endtabs %}

### Components

The following diagram describes the different components of the CARTO Self-hosted. This set of components maps both with a container or external service in the deployment.

<figure><img src="https://3029946802-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FybPdpmLltPkzGFvz7m8A%2Fuploads%2Fgit-blob-e785253708216cc25e0739a34b55f6448dbc1309%2FSelf-Hosted%20Architecture%20Diagram.jpg?alt=media" alt=""><figcaption></figcaption></figure>

{% hint style="info" %}
Kots is only used in "[Single VM](https://docs.carto.com/carto-self-hosted/deployment-guides/single-vm-deployment)" deployments and standard "[Orchestrated containers](https://docs.carto.com/carto-self-hosted/deployment-guides/kubernetes)" deployments
{% endhint %}

#### **router-http**

It's the principal entry point of the application. It's an [nginx reverse proxy](https://docs.nginx.com/nginx/admin-guide/web-server/reverse-proxy/) to route the HTTPs traffic to the right components.

#### **metadata-database**

PostgreSQL database to manage the metadata of the CARTO platform.

Subscribers and APIs use this database to perform their operations.

More info at the [external database ](https://docs.carto.com/carto-self-hosted/deployment-requirements#external-database)section in [deployment requirements](https://docs.carto.com/carto-self-hosted/key-concepts/deployment-requirements).

#### **message-broker**

Message broker to exchange messages between the different pieces of the platform using the producer-consumer paradigm.

APIs or scheduler processes often produce messages to be consumed by the subscriber. For example, [Imports API](https://api-docs.carto.com/#d8fea1d4-2f80-4270-a684-75fd83b10426) produces a message to import a file, and the import-worker consumes the message and performs the import operation.

It's not a container included in the Self-Hosted, it uses [Google Cloud Pub/Sub](https://cloud.google.com/pubsub).

#### redis

In-memory [redis](https://redis.com/) cache for the APIs and subscribers.

CARTO Self-Hosted can work without this cache, the platform will just fall back the queries against the metadata database.

You can use an external service of your cloud provider as explained in more detail [here](https://docs.carto.com/carto-self-hosted/guides/guides/configure-an-external-in-memory-cache).

#### **workspace-www**

The Web Application of the workspace. It's a modularized React application. Applications in the CARTO platform such as [Builder](https://docs.carto.com/carto-user-manual/maps) or [Workflows](https://docs.carto.com/carto-user-manual/workflows) are inside this container.

It's the root path (<https://carto.mycompany.com>) of the Self-Hosted, a basic nginx container with static files like HTML, CSS, and JS.

#### **accounts-www**

The Web Application manages the login and signup process. It's a modularized React application.

It's at <mark style="color:orange;">/acc/</mark> path (<https://carto.mycompany.com/acc>) of the Self-Hosted, a basic nginx container with static files like HTML, CSS, and JS.

It requires a connection with the CARTO accounts API to perform different operations: create accounts, create users, invite users, etc.

#### http-cache

An HTTP cache that works as a CDN for the [maps-api](#maps-api) and some endpoints of [workspace-api](#workspace-api). It uses [Varnish](https://varnish-cache.org/) HTTP Cache.

#### workspace-api

API to support the Web Application of the workspace (workspace-www).

#### maps-api

[Maps](https://docs.carto.com/carto-for-developers/key-concepts/apis#maps) and [SQL](https://docs.carto.com/carto-for-developers/key-concepts/apis#sql) high-performance API. It's the component with higher traffic as it's deeply used by other components.

It doesn't perform batch operations. Batch operations of SQL API are executed by sql-worker.

You should create multiple instances of this container to scale at your needs.

#### import-api

[Import API](https://api-docs.carto.com/#d8fea1d4-2f80-4270-a684-75fd83b10426). This component doesn't perform actual import operation, it just creates jobs for [import-worker.](#import-worker)

#### lds-api

[Location Data Services (LDS](https://docs.carto.com/carto-for-developers/key-concepts/apis#location-data-services-lds)) API.

#### workspace-subscriber

Consumer of the messages related to workspace at the Message Broker. It reads the messages published on that bus and performs the required actions.

#### import-worker

Consumer of the messages related to [imports](https://docs.carto.com/carto-for-developers/key-concepts/apis#imports) at the Message Broker. It uploads geospatial files into the customer Data Warehouse.

It requires 8GB of RAM to process up to 1GB of geospatial files.

#### sql-worker

Consumer of the messages related to [SQL](https://docs.carto.com/carto-for-developers/key-concepts/apis#sql) at the Message Broker.

This worker is mainly used to execute SQL in batch for customers using PostgreSQL, Amazon Redshift, and Oracle data warehouses.

Connections to BigQuery, Snowflake, and Databricks data warehouses won't use this component as it uses the batch APIs (jobs) provided by the data warehouse.

#### cdn-invalidator-sub

Consumer of the messages related to invalidation at the Message Broker. It invalidates content at [http-cache](#http-cache).

#### ai-proxy

A LLM proxy used to interact with the different AI providers (including your own providers) that CARTO supports. This component is optional, and only [required if you plan to use CARTO AI](https://docs.carto.com/carto-self-hosted/guides/guides-helm/configure-carto-ai-prerequisites-helm).

#### ai-api

API that provides the capabilities for running the AI features offered by CARTO platform. This component is optional, and only [required if you plan to use CARTO AI](https://docs.carto.com/carto-self-hosted/guides/guides-helm/configure-carto-ai-prerequisites-helm).

#### **kots**

{% hint style="info" %}
These containers are deployed just in the Single VM and in the standard Orchestrated container deployment methods
{% endhint %}

Containers used for the deployment of the Admin Console. They serve the statics needed to handle the Admin Console.

This piece manages the changes applied to your CARTO Self-Hosted configuration, and it handles licensing related processes and upgrade checks.


---

# Agent Instructions: 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:

```
GET https://docs.carto.com/carto-self-hosted/key-concepts/architecture.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.