> 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/aprender/arquitetura/projetos-environments-namespaces-e-workloads.md).

# Projetos, environments, namespaces e workloads

Como o skail identifica a sua aplicação e separa o que é de quem. Quatro conceitos em uma hierarquia, e três variáveis do runtime que saem dela.

## A hierarquia

Um projeto agrupa uma iniciativa ou produto. Dentro dele existem environments, os estágios do ciclo de vida. Em cada environment são publicados workloads, as aplicações que executam as functions. Uma `[SkailFunction]` pertence a um workload; o workload roda em um environment; o environment pertence a um projeto.

```
projeto: faturamento
├── environment: dev    (namespace tenant/dev-id,  chave dev)
│   └── workload: cobranca:v1.3.0
├── environment: hml    (namespace tenant/hml-id,  chave hml)
│   └── workload: cobranca:v1.3.0
└── environment: prod   (namespace tenant/prod-id, chave prod)
    ├── workload: cobranca:v1.2.2   (execuções antigas terminando)
    └── workload: cobranca:v1.3.0
```

O projeto é onde tudo vive, o environment é em qual estágio está rodando, o workload é o que está executando.

## Projeto

Identificado pelo nome cadastrado no portal (`faturamento`, `logistica`, `portal-cliente`). Reúne os environments, os workloads e os acessos de uma mesma iniciativa. É a fronteira de organização: quem tem acesso ao projeto enxerga seus environments e workloads; workloads são sempre publicados dentro de um projeto.

## Environment

Identificado pelo nome (`dev`, `hml`, `prod`) dentro do projeto. É a fronteira de isolamento: workloads publicados em um environment só recebem execuções destinadas a ele; execuções e eventos não cruzam environments; o Monitor é segmentado por environment. Cada environment aponta para os próprios recursos externos (banco, APIs de terceiros) por meio da configuração da sua aplicação.

Cada environment tem uma chave e um namespace, e é isso que a aplicação e quem dispara usam para se identificar.

## Namespace

O namespace é a identidade do environment para a API, no formato `tenant/environment` (ids, como aparecem na tela do environment no portal). Vai em `SKAIL_NAMESPACE` no runtime e no header `Skail-namespace` de toda chamada HTTP. O skail confere que a chave (`SKAIL_KEY`, header `skail-key`) pertence àquele environment. Chave de `dev` com namespace de `prod` é recusada.

## Workload

Identificado por nome e versão, `nome:versao` (`cobranca:v1.3.0`). É a aplicação vista pelo skail e a unidade de endereçamento: cada function e command recebe o endereço `{nome}:{versao}/{NomeDoMetodo}`, e é para esse endereço que as execuções são entregues. Vai em `SKAIL_WORKLOAD` no runtime.

A versão faz parte do endereço. Uma execução iniciada em `cobranca:v1.2.2` continua endereçada a `v1.2.2` até terminar; publicar `v1.3.0` não a move. Por isso duas versões do mesmo workload podem conviver no mesmo environment enquanto as execuções antigas esvaziam. Ver [Versionamento de código com execuções em andamento](/aprender/fundamentos/versionamento-de-codigo-com-execucoes-em-andamento.md).

Um mesmo par nome e versão pode estar publicado em mais de um environment ao mesmo tempo (`v1.3.0` em `hml` para validação e em `prod` atendendo clientes): o mesmo build, com variáveis diferentes.

## Como isso vira configuração

| No portal                      | No runtime da aplicação              | Na API HTTP (quem dispara)                       |
| ------------------------------ | ------------------------------------ | ------------------------------------------------ |
| Environment: namespace         | `SKAIL_NAMESPACE=tenant/environment` | header `Skail-namespace`                         |
| Environment: chave             | `SKAIL_KEY=...`                      | header `skail-key`                               |
| Environment: endereço do skail | `SKAIL_SIDECAR=...`                  |                                                  |
| Environment: URL base da API   |                                      | `https://SEU_SKAIL_BASE_URL`                     |
| Workload: nome e versão        | `SKAIL_WORKLOAD=cobranca:v1.3.0`     | caminho `/trigger/cobranca/v1.3.0/{funcao}/{id}` |

Se `SKAIL_WORKLOAD` não bater com o workload publicado, a aplicação sobe mas nenhuma execução chega a ela ("Target method not found" no runtime, execução parada em Na fila no Monitor). Se o namespace ou a chave não baterem, 401 ou 403.

## Próximos passos

[Ambientes e promoção](/operar/readme.md) descreve o fluxo dev, hml, prod na prática. [Como configurar o runtime](/construir/configurar-e-hospedar/como-configurar-o-runtime.md) tem as quatro variáveis. A referência das telas está em [Projetos](/construir/portal/projetos.md), [Environments](/construir/portal/environments.md) e [Workloads](/construir/portal/workloads.md).