---
source: https://carbone.io/documentation/developer/under-the-hood/architecture-guideline.html
title: "Architecture guideline"
description: "Calling sequences, template management, privacy, and self-hosted deployment considerations"
generated_at: "2026-07-24"
---

# Architecture guideline

Calling sequences, template management, privacy, and self-hosted deployment considerations

## Introduction

Carbone Cloud is a turnkey solution that can be easily integrated into any environment.

Here are a few architectural points you can take into account to optimize your document production.

## Calling Sequence

### Synchronous / Asynchronous

By default, the Carbone API can be used in synchro mode, as shown in the diagram below:

![Carbone Synchronious Call](/img/doc/carbone-sync-call.svg)

When you send your data to generate a report, the API returns when the document is produced and available.

In some cases, for long renderings (several hundred pages) or when using [Batch processing](/documentation/developer/http-api/generate-reports.md#batch-processing), asynchronous mode is required. In this case, you must add a webhook url in the `carbone-webhook-url` header.

[Asynchronous jobs documentation](/documentation/developer/http-api/generate-reports.md#asynchronous-jobs)

The call sequence is then as follows:

![Carbone Asynchronious Call](/img/doc/carbone-async-call.svg)

### Render and Download with single API call

You can also optimize callflow by retrieving the final file when calling `POST /render/:idTemplate`.

To do this, simply add the query parameter `?download=true`. [Here is documentation](/documentation/developer/http-api/generate-reports.md#direct-download)

Here's the calling sequence:

![Carbone single Call](/img/doc/carbone-single-call.svg)

> ℹ️ **Note:** Please note that you need to be able to handle HTTP calls to retrieve a file in response to a `POST`.

## Template management

There are several ways to manage templates:

-   Template management from [Carbone Studio](https://studio.carbone.io)

You need to load your templates into the studio, then retrieve the `templateID` and insert it into your API calls.

-   Using the API

You then push your templates to our [API](/documentation/developer/http-api/manage-templates.md#upload-a-template) `POST /template` and retrieve the `templateID` programmatically.

-   Using volatile templates

You can decide to send the template in a volatile way, with each generation call. You must then call the API `POST /render/template` with the following body

```text
  {
    data      : {},
    template  : "base64-encoded-file",
    convertTo : "pdf"
  }
```

-   Using embedded Studio

You can add template management to your application by [embedding the studio](/documentation/developer/embedding/studio-web-component.md). You can then allow your users to modify or create new templates without leaving your application. The `templateID` is then retrieved by Studio events.

## Privacy

Carbone's design is security-based. Our tool uses the minimum of information and does not store or log any json data from your renders.

We comply with the General Data Protection Regulation and Carbone's infrastructure is entirely based in Europe (in France and Germany) to guarantee the maximum protection of your data.

However, if your safety requirements are more challenging, you can also use Carbone in your infrastructure.

## Carbone self hosted

Using the Cloud version is recommended for most users.

You can, however, set up a [self-hosted instance of Carbone](/documentation/developer/on-premise-installation/introduction.md) if you wish:

-   Airgap environment (Carbone generation in an environment without Internet access)
-   use of sensitive data that cannot be transmitted over the Internet
-   heavy workloads with very high rendering volumes
-   use of specific fonts or specific formatters

You can run Carbone from your [Linux](/documentation/developer/on-premise-installation/install-on-linux.md) or [MacOS](/documentation/developer/on-premise-installation/install-on-macos.md) machine, but also deploy on [AWS with ECS](/documentation/developer/self-hosted-deployment/deploy-on-aws-ecs.md), [GCP with Cloud Run](/documentation/developer/self-hosted-deployment/deploy-on-gcp.md), [Azure with Container Apps](/documentation/developer/self-hosted-deployment/deploy-on-azure.md) or in your [Kubernetes Cluster](/documentation/developer/self-hosted-deployment/deploy-on-kubernetes.md).

### Carbone on AWS

If your infrastructure is already deployed on AWS, Carbone is also available on the AWS Marketplace. Using this solution, you can benefit from our tool in just a few minutes, with invoicing generated directly by AWS. [Read more](/documentation/developer/self-hosted-deployment/deploy-on-aws.md)

## Related topics

- [How Carbone works](/documentation/developer/under-the-hood/overview.md)