> 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/comece-aqui/como-funciona.md). # Como funciona O modelo mental inteiro em uma página: o que você escreve, o que roda na sua infraestrutura, o que o skail faz por você, e as etapas de uma execução, do disparo ao Monitor. ## Cinco componentes ``` SUA INFRAESTRUTURA SKAIL ┌──────────────────────────────────────────┐ ┌──────────────────────────┐ │ Sua aplicação │ │ API HTTP: trigger, fire │ │ ┌────────────────────────────────────┐ │ │ │ │ │ function orquestra o fluxo │ │ │ Histórico de cada │ │ │ command executa I/O │ │ │ execução, esperas e │ │ └────────────────────────────────────┘ │ ◄──────► │ eventos │ │ Runtime do skail (pacote do SDK) │ │ │ │ ┌────────────────────────────────────┐ │ │ Portal: projetos, │ │ │ descobre métodos, faz replay, │ │ │ environments, workloads,│ │ │ busca trabalho, grava cada passo │ │ │ Monitor, Time Travel │ │ └────────────────────────────────────┘ │ │ Debug │ └──────────────────────────────────────────┘ └──────────────────────────┘ ▲ Quem dispara: seu controller, webhook, job, │ outro sistema, qualquer linguagem ──► POST /trigger ────────────┘ POST /api/v1/fire ``` O SDK é o que você adiciona ao projeto. Com ele, você marca como function o método que orquestra o fluxo, e como command cada método que faz uma operação de I/O (banco, HTTP, fila, e-mail) ou que produz um valor que muda a cada execução (hora atual, id gerado). O runtime é um pacote dentro da sua aplicação. Ele registra os métodos marcados, busca trabalho no skail, executa suas functions e commands e grava cada passo. Roda onde a sua aplicação roda: container, Kubernetes, VM. O skail é a plataforma, operada pelo skail. Ela acompanha cada execução passo a passo, 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; o que você opera é a sua aplicação. A API HTTP é a porta de entrada. `POST /trigger/...` inicia uma execução; `POST /api/v1/fire/...` acorda uma execução que está esperando um evento. Qualquer sistema chama essas duas rotas. O portal é onde você cria projetos, environments e workloads, obtém chaves, e acompanha cada execução no Monitor, passo a passo, com a opção de depurar uma execução de produção na sua IDE com o Time Travel Debug. ## Uma execução, do começo ao fim Um controller do seu sistema recebe um pedido e faz `POST /trigger/vendas/v1.0.0/ProcessarPedido/{pedidoId}` com os argumentos em JSON. O skail registra o início da execução e a entrega à aplicação que publica o workload `vendas:v1.0.0`. A sua aplicação, com o runtime rodando, recebe a execução e chama `ProcessarPedido`. A function chega em `await ReservarEstoque(pedidoId)`, um command: o runtime executa, grava o resultado no histórico da execução e segue. A function chega a um delay de 24 horas: o runtime grava o passo, agenda a retomada para dali a 24 horas e libera o processo. Nenhuma thread fica presa; a aplicação pode até ser reiniciada. Vinte e quatro horas depois, o skail acorda a execução e a entrega de novo à sua aplicação. O runtime chama `ProcessarPedido` desde a primeira linha (isso é o replay). Em `await ReservarEstoque(...)` encontra o resultado gravado e devolve sem executar. No delay, encontra o passo concluído e segue. Chega em `await CobrarCartao(pedidoId)`, que ainda não rodou: executa, grava, e a function termina. O skail marca a execução como concluída e ela aparece assim no Monitor, com os três passos e o tempo de cada um.
Duas entregas da mesma execução: na primeira, command 1 conclui e o processo cai durante o delay de 24 horas; na segunda, o replay traz os passos do histórico, command 2 roda e a execução é concluída.
Se `CobrarCartao` tivesse falhado, o skail reentregaria a execução e o runtime faria o replay de novo: os passos gravados voltam do histórico, `CobrarCartao` roda outra vez, até cinco vezes por padrão. Se esgotar, a exceção chega à function como uma exceção comum de `async`/`await`, e você pode tratá-la com `try/catch`. Se a function não tratar, ela falha e é reentregue até o `retryCount` dela (15 por padrão), sem repetir os commands já concluídos. ## As três regras que decorrem disso * A function é reexecutada, então ela não pode fazer I/O nem ler o relógio: isso mora nos commands. * O command grava o resultado e não roda de novo depois disso, mas pode rodar de novo se falhar antes de gravar: por isso a chamada externa leva uma chave de idempotência. * Uma execução em andamento referencia o código da versão em que começou: mudar a sequência de awaits de uma function com execuções em andamento exige versionar. ## Próximos passos
:bolt:QuickstartPara ver isso rodando em dez minutos.Quickstart (10 min)
:diagram-project:Modelo de programaçãoPara o detalhe de function e command.Functions e commands
:layer-group:Visão geral dos componentesPara o que roda onde.Visão geral dos componentes