> For the complete documentation index, see [llms.txt](https://docs.skail.dev/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.skail.dev/construa/conceitos/arquitetura/visao-geral-dos-componentes.md).

# Visão geral dos componentes

A arquitetura tem quatro componentes. Dois ficam na sua infraestrutura, dentro da sua aplicação: o SDK e o runtime. Os outros dois ficam no skail: a plataforma, que atende a API HTTP, e o portal. Esta página diz o que cada componente faz e onde roda.

<figure><img src="https://1898946878-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FsJmS5ILPG5x2x5j0WyiV%2Fuploads%2F9zzEHlwxaVMvT73znoz8%2Fap-arq-componentes.svg?alt=media" alt="Na sua infraestrutura, quem dispara (seu controller, webhook ou job) chama a API HTTP do skail com POST /trigger e POST /api/v1/fire, e a sua aplicação traz o SDK, com a marcação de functions e commands e as primitivas de espera, e o runtime, que busca trabalho no skail e executa e registra cada passo; o seu banco e as suas APIs são acessados pelos commands. No skail, a plataforma recebe a API HTTP, entrega o trabalho, mantém cada execução viva, agenda as esperas por tempo, entrega os eventos externos e reentrega quando algo falha, trocando execuções, passos e esperas com o runtime. O portal traz o Monitor e o Time Travel Debug."><figcaption></figcaption></figure>

## Do seu lado

### SDK

O que você adiciona ao projeto: em C#, o pacote `Skail.Platform.Runtime`; em TypeScript, os pacotes `@skail/runtime` e `@skail/build`. O SDK traz a marcação de functions e commands, as primitivas de espera (delay, espera por evento, esperar todos, esperar o primeiro) e o contexto da execução. As regras de assinatura são cobradas antes de a aplicação rodar: em C#, por um analyzer na compilação; em TypeScript, pelo `skail build`. O SDK não roda nada por si: é a forma de escrever código que o runtime sabe executar. Ver [Modelo de programação](/construa/conceitos/functions-e-commands.md) e [SDKs e linguagens](/referencia/sdk-typescript-e-outras-linguagens.md).

### Runtime

Vem com o SDK e roda dentro do processo da sua aplicação, registrado na configuração do host: em C#, por `builder.UseSkail()`; em TypeScript, por `createSkailPlatform`. Faz quatro coisas:

* identifica as functions e commands da aplicação;
* busca trabalho no skail;
* executa functions e commands, registrando cada passo concluído e pulando, na retomada, o que já foi feito (o replay);
* exporta telemetria.

Roda onde a sua aplicação roda: worker, container, Kubernetes, VM. Escala com réplicas da sua aplicação. Ver [Runtime](/construa/conceitos/arquitetura/runtime.md).

{% hint style="info" %}
Do seu lado não entra nada novo para operar: seu banco continua sendo seu banco, acessado pelos commands, e o runtime não precisa de banco, disco nem fila próprios.
{% endhint %}

## Do lado do skail

### O skail

A plataforma, operada pelo skail. Recebe as chamadas da API HTTP (trigger e fire), entrega o trabalho à aplicação que publica o workload, mantém cada execução viva entre um passo e outro, agenda as esperas por tempo, entrega os eventos externos às execuções que os aguardam e reentrega o trabalho quando algo falha. Você não instala, escala nem monitora nada dela. Ver [O que o skail faz pela sua execução](/construa/conceitos/arquitetura/o-que-o-skail-faz-pela-sua-execucao.md).

{% hint style="warning" %}
Argumentos e resultados de commands fazem parte da execução e aparecem na linha do tempo do Monitor; por isso, passe ids e valores de decisão, não cadastros inteiros (ver [Segurança](/referencia/garantias/seguranca.md)).
{% endhint %}

### Portal

Onde você cria projetos, environments e workloads, obtém chave, namespace e URL base, acompanha as execuções no Monitor e exporta uma captura para o Time Travel Debug. Ver [Portal](/construa/conceitos/arquitetura/portal.md).

## Como se encaixam

```
seu controller / webhook / job         ──POST /trigger, /api/v1/fire──►        skail (API HTTP)
                                                                               │
sua aplicação                          ◄──── execuções, passos, esperas ────►  skail: entrega o trabalho, agenda
  runtime + SDK                                                                │  esperas, entrega eventos
  functions e commands                                                         │
  seu banco, suas APIs (via commands)                                          ▼
                                                                               portal (Monitor, TTD)
```

O trigger entra pelo skail e vira uma execução do workload. A sua aplicação recebe a execução, chama a function e conclui um passo a cada `await`. Um delay ou uma espera por evento hiberna a execução: a sua aplicação fica livre, e o prazo ou o fire acordam a execução, que volta para a sua aplicação e continua do passo seguinte. O Monitor desenha essa sequência como linha do tempo.

## Próximos passos

[Runtime](/construa/conceitos/arquitetura/runtime.md) e [O que o skail faz pela sua execução](/construa/conceitos/arquitetura/o-que-o-skail-faz-pela-sua-execucao.md) detalham os dois lados. [Projetos, environments, namespaces e workloads](/construa/conceitos/arquitetura/projetos-environments-namespaces-e-workloads.md) explica como a sua aplicação é identificada. [Garantias de execução](/referencia/garantias/garantias-de-execucao.md) diz o que essa arquitetura promete.