# Backend Services

Esta página fornece uma visão geral abrangente de todos os serviços backend do Decentraland, seus papéis arquiteturais e como interagem dentro do ecossistema. Para especificações detalhadas de API e endpoints, consulte o [Referência de API](https://github.com/decentraland/docs/blob/main/apis/README.md) seção.

## Arquitetura de Serviço

O backend do Decentraland é composto por microserviços distribuídos organizados em camadas lógicas:

* **Camada Descentralizada** - Rede Catalyst e infraestrutura de entrega de conteúdo
* **Camada de Comunicações em Tempo Real** - Descoberta de serviços e comunicações peer-to-peer
* **Serviços de Funcionalidade** - Funcionalidade voltada ao usuário (conteúdo, economia, gamificação)
* **Serviços Centrais** - Infraestrutura essencial da plataforma (auth, marketplace, notifications)

***

## Camada Descentralizada

### Catalyst

**Propósito**: Rede de entrega de conteúdo descentralizada

A rede Catalyst forma a base da infraestrutura de conteúdo do Decentraland. Cada nó Catalyst é um servidor completo que fornece:

* **Content Server** - Armazenamento e recuperação de entidades (scenes, profiles, wearables)
* **Serviço Lambdas** - Endpoints utilitários e consultas de conteúdo
* **Servidor de Comunicações** - Transporte de mensagens em tempo real

**Papel Arquitetural**: Os nós Catalyst são distribuídos geograficamente e permissionless. A rede fornece redundância e disponibilidade de conteúdo sem controle central.

**Integrações Principais**:

* Realm Provider - Anuncia disponibilidade do nó
* Asset Bundle Registry - Aciona otimização de ativos no deployment
* Archipelago Workers - Fornece dados de ilha/cluster

**Referência de API**: [API do Catalyst](https://github.com/decentraland/docs/blob/main/apis/catalyst/overview/README.md)

### Lamb2

**Propósito**: Utilitários Lambda e funções serverless

Lamb2 fornece endpoints utilitários para consumo de conteúdo e consultas que complementam o Content Server:

* Agregação e filtragem de scenes
* Consultas de profile com fallbacks
* Verificações de status e health checks

**Papel Arquitetural**: Atua como uma camada de conveniência sobre o acesso bruto a entidades do Content Server, fornecendo padrões de consulta de nível mais alto comumente necessários pelos clientes.

**Referência de API**: [Lamb2 API](https://github.com/decentraland/docs/blob/main/apis/lamb2/overview/README.md)

***

## Camada de Comunicações em Tempo Real

### Realm Provider

**Propósito**: Descoberta de serviços e seleção de realm

O Realm Provider é o ponto de entrada para todos os clientes do Decentraland. Ele implementa seleção inteligente de realm com base em:

* **Otimização geográfica** - Roteia usuários para os nós Catalyst mais próximos
* **Monitoramento de saúde** - Filtra nós com problemas ou sobrecarregados
* **Rastreamento de capacidade** - Fornece contagens de usuários por realm em tempo real
* **Agregação de cenas populares** - Identifica locais populares em todos os realms

**Papel Arquitetural**: Fonte única de verdade para a infraestrutura disponível. Os clientes consultam-no uma vez na inicialização para descobrir todos os endpoints de serviço (Catalyst, Comms, BFF).

**Integrações Principais**:

* Consulta todos os nós Catalyst periodicamente
* Agrega estatísticas do Archipelago
* Fornece visão unificada da rede distribuída

**Referência de API**: [Realm Provider API](https://github.com/decentraland/docs/blob/main/apis/realm-provider/overview/README.md)

### Comms Gatekeeper

**Propósito**: Controle de acesso a voz e vídeo

O Gatekeeper gerencia o acesso aos servidores de mídia LiveKit para chat de voz e vídeo:

* **Geração de tokens** - Cria tokens de acesso com tempo limitado e permissões específicas
* **Administração de scenes** - Gerencia direitos de admin de scene e banimentos
* **Gerenciamento de stream** - Controla acesso a transmissão ao vivo e chaves RTMP
* **Controles de privacidade** - Impõe permissões de chat de voz privado

**Papel Arquitetural**: Camada de segurança entre clientes e infraestrutura de mídia. Evita acesso não autorizado enquanto habilita modelos de permissão flexíveis (baseados em scene, privado, comunidade).

**Integrações Principais**:

* LiveKit - Emite tokens JWT para acesso ao servidor de mídia
* Worlds API - Valida propriedade de world para direitos de admin
* Signed Fetch - Autentica todas as requisições via assinaturas de wallet

**Referência de API**: [Comms Gatekeeper API](https://github.com/decentraland/docs/blob/main/apis/comms-gatekeeper/overview/README.md)

### Archipelago Workers

**Propósito**: Agrupamento de comunicações e roteamento de mensagens

Archipelago implementa o protocolo de clustering baseado em proximidade que agrupa jogadores próximos em "ilhas":

* **Transporte WebSocket** - Mantém conexões persistentes com clientes
* **Rastreamento de posição** - Monitora localizações dos jogadores em tempo real
* **Formação de ilhas** - Agrupa dinamicamente jogadores com base na distância
* **Roteamento de mensagens** - Encaminha mensagens apenas para membros da ilha

**Componentes da Arquitetura**:

* **Conector WebSocket** - Lida com conexões de clientes e autenticação
* **Núcleo do Archipelago** - Implementa algoritmo de clustering e gerenciamento de ilhas
* **Serviço de Estatísticas** - Fornece métricas de conexão e contagens de usuários
* **Integração com NATS** - Publica atualizações de posição e roteia mensagens

**Papel Arquitetural**: Otimiza comunicações peer-to-peer limitando o fanout de mensagens. Em vez de transmitir para todos os usuários em um realm, as mensagens alcançam apenas jogadores dentro do alcance de interação.

**Integrações Principais**:

* Broker de mensagens NATS - Roteamento distribuído de mensagens
* Realm Provider - Fornece estatísticas de ilhas
* Places API - Dados de contagem de usuários para cenas populares

**Referência de API**: [API dos Archipelago Workers](https://github.com/decentraland/docs/blob/main/apis/archipelago-workers/overview/README.md)

***

## Serviços de Funcionalidade

### Worlds

**Propósito**: Hospedagem isolada de scenes fora da grade principal

Worlds permite que usuários implantem scenes em ambientes isolados:

* **Worlds nomeados** - Acessível via URLs personalizadas (por exemplo, `world.dclworlds.com`)
* **Worlds privados** - Controle de acesso gateado por NFT
* **Permissões de World** - Direitos de admin e deployment gerenciados pelo owner

**Papel Arquitetural**: Estende o modelo de conteúdo do Decentraland além da grade fixa de LAND. Cada world é uma scene independente com seus próprios canais de comunicação e controle de acesso.

**Integrações Principais**:

* Consulta indexadores de blockchain para verificação de propriedade de NFT
* Publica atualizações de world para NATS para sincronização de clientes em tempo real
* Integra-se com Comms Gatekeeper para salas de chat de voz
* Aciona pipeline de processamento de ativos no deployment

**Referência de API**: [Worlds API](https://github.com/decentraland/docs/blob/main/apis/worlds/overview/README.md)

### Eventos

**Propósito**: Gestão e descoberta de eventos in-world

Gerencia o ciclo de vida completo de eventos virtuais:

* **CRUD de eventos** - Criação, atualizações e agendamento
* **Rastreamento de participantes** - Participação de usuários e RSVPs
* **Descoberta** - Consultas e filtragem baseadas em tempo
* **Notificações** - Integração com Events Notifier

**Papel Arquitetural**: Fornece contexto temporal ao metaverso. Eventos impulsionam descoberta e engajamento de usuários ao destacar experiências sensíveis ao tempo.

**Referência de API**: [Events API](https://github.com/decentraland/docs/blob/main/apis/events/overview/README.md)

### Places

**Propósito**: Descoberta e curadoria de pontos de interesse

Agrega e seleciona locais interessantes pelo Decentraland:

* **Cenas populares** - Popularidade em tempo real baseada em contagens de usuários
* **Lugares em destaque** - Locais selecionados editorialmente
* **Busca e filtragem** - Descoberta por tags, categorias
* **Metadados de POI** - Descrições, miniaturas, coordenadas

**Papel Arquitetural**: Resolve o problema de descoberta em um grande mundo aberto. Agrega dados de múltiplas fontes para ajudar usuários a encontrar conteúdo envolvente.

**Integrações Principais**:

* Catalyst - Metadados de scene e informações de deployment
* Archipelago Stats - Contagens de usuários por scene em tempo real
* Comms Gatekeeper - Disponibilidade e status de realm

**Referência de API**: [Places API](https://github.com/decentraland/docs/blob/main/apis/places/overview/README.md)

### Atlas Server

**Propósito**: Dados de mapa e visualização de parcelas

Fornece dados abrangentes do mapa mundial:

* **Propriedade de parcel** - Dados de LAND indexados em blockchain
* **Metadados de scene** - Nomes de scenes implantadas e coordenadas
* **Tiles de mapa** - Imagens de tiles pré-renderizadas para exibição em UI
* **Consultas espaciais** - Encontra parcels por coordenadas ou owner

**Papel Arquitetural**: Fornece o índice espacial para a grade de LAND do Decentraland. Essencial para UIs de mapa e navegação espacial.

**Referência de API**: [Atlas Server API](https://github.com/decentraland/docs/blob/main/apis/atlas-server/overview/README.md)

### Camera Reel

**Propósito**: Gestão de screenshots geradas pelos usuários

Gerencia screenshots e imagens de usuários:

* **Uploads de imagem** - Armazenamento autenticado de imagens
* **Organização de galeria** - Coleções de screenshots do usuário
* **Metadados** - Local da scene, timestamp, tags

**Papel Arquitetural**: Habilita compartilhamento de conteúdo e recursos sociais em torno de fotografia gerada pelos usuários.

**Referência de API**: [Camera Reel API](https://github.com/decentraland/docs/blob/main/apis/camera-reel/overview/README.md)

### Exploration Games

**Propósito**: Gamificação de onboarding e tutoriais

Sistema de quests interativas para onboarding de novos usuários:

* **Rastreamento de quests** - Progresso através de missões tutoriais
* **Conclusão de desafios** - Verificação de tarefas
* **Integração de recompensas** - Conecta-se ao sistema de rewards

**Papel Arquitetural**: Reduz atrito para novos usuários fornecendo uma introdução estruturada e orientada a objetivos às funcionalidades do Decentraland.

**Referência de API**: [Exploration Games API](https://github.com/decentraland/docs/blob/main/apis/exploration-games/overview/README.md)

***

## Serviços Centrais

### Auth Server

**Propósito**: Autenticação baseada em wallet e gestão de sessão

Implementa o modelo de autenticação wallet-first do Decentraland:

* **Verificação de assinatura** - Valida assinaturas de wallet Ethereum
* **Emissão de tokens JWT** - Gera tokens de sessão
* **Validação de tokens** - Verifica tokens para recursos protegidos
* **Ciclo de vida da sessão** - Atualização e expiração de tokens

**Papel Arquitetural**: Fornece verificação de identidade descentralizada. Usuários se autenticam via assinaturas de wallet em vez de senhas, alinhando-se aos princípios Web3.

**Fluxo de Autenticação**:

1. Cliente solicita challenge
2. Usuário assina challenge com wallet
3. Auth Server verifica assinatura e emite JWT
4. Cliente inclui JWT em requisições API subsequentes

**Referência de API**: [Auth Server API](https://github.com/decentraland/docs/blob/main/apis/auth-server/overview/README.md)

### Serviço Social

**Propósito**: Grafo social e gestão de comunidade

Gerencia relacionamentos sociais e comunidades:

* **Sistema de amigos** - Pedidos, aprovações, listas de amigos
* **Lista de bloqueio** - Bloqueio de usuários e privacidade
* **Comunidades** - Associação a grupos e descoberta
* **Status em tempo real** - Notificações de amigos online/offline via NATS
* **Mensagens privadas** - Infraestrutura de mensagens diretas

**Papel Arquitetural**: Fornece a camada social que transforma o Decentraland de um mundo virtual em um metaverso social.

**Integrações Principais**:

* Catalyst Client - Busca dados de profile para amigos
* NATS - Publica atualizações de status de amigos
* Archipelago - Consulta status online e localizações

**Referência de API**: [Social Service API](https://github.com/decentraland/docs/blob/main/apis/social-service/overview/README.md)

### Marketplace Server

**Propósito**: Integração com marketplace de NFT

Backend para o marketplace de wearables e emotes do Decentraland:

* **Consultas de listagem** - Navegar e buscar itens do marketplace
* **Histórico de transações** - Registros de compra
* **Dados de precificação** - Preços de mercado e tendências
* **Metadados de coleção** - Coleções de wearables e emotes

**Papel Arquitetural**: Faz a ponte entre dados on-chain de NFT e a UI amigável do marketplace. Indexa eventos da blockchain para consultas rápidas.

**Referência de API**: [Marketplace Server API](https://github.com/decentraland/docs/blob/main/apis/marketplace-server/overview/README.md)

***

## Serviços de Ativos

### Registro de Pacotes de Assets

**Propósito**: Gestão otimizada de ativos

Registro de bundles de ativos otimizados para a plataforma:

* URLs de asset bundle por plataforma
* Versionamento
* Distribuição CDN

**Referência de API**: [Asset Bundle Registry API](https://github.com/decentraland/docs/blob/main/contributor/apis/asset-bundle-registry/README.md)

**Componentes do Sistema**:

* **Conversor de Bundle de Ativos** - Constrói bundles específicos por plataforma
* **Gerador de LODs** - Cria variantes de nível de detalhe

**Fluxo de Processos**:

{% @mermaid/diagram content="sequenceDiagram
participant Catalyst
participant Queue as Deployments Queue
participant Converter as AB Converter
participant Registry

```
Catalyst->>Queue: New deployment
Queue->>Converter: Process assets
Converter->>Converter: Build bundles
Converter->>Registry: Register bundles" %}
```

### Camera Reel

**Propósito**: Gestão de screenshots e imagens

Gestão de conteúdo gerado por usuários:

* Armazenamento de screenshots
* Uploads de imagem
* Organização de galeria

**Referência de API**: [Camera Reel API](https://github.com/decentraland/docs/blob/main/contributor/apis/camera-reel/README.md)

### Credits Server

**Propósito**: Moeda virtual e economia

Gerencia o sistema de créditos virtuais do Decentraland:

* **Rastreamento de saldo** - Saldos de créditos dos usuários
* **Livro-razão de transações** - Transferências e gastos de créditos
* **Integração de compra** - Conversão de fiat para credits
* **Sincronização com blockchain** - Consulta indexadores para saldos on-chain

**Papel Arquitetural**: Fornece uma alternativa de moeda com menor atrito aos tokens on-chain para compras e funcionalidades dentro do mundo.

**Referência de API**: [Credits Server API](https://github.com/decentraland/docs/blob/main/apis/credits-server/overview/README.md)

### Badges

**Propósito**: Sistema de conquistas e gamificação

Concessões de badges acionadas por eventos:

* **Definições de badge** - Conquistas disponíveis
* **Inventário do usuário** - Badges conquistados por usuário
* **Concessão automática** - Prêmios de badge acionados por eventos

**Componentes da Arquitetura**:

* **Badges API** - Consultas de badge e inventários de usuários
* **Processador de Badges** - Escuta Events Notifier e concede badges

**Papel Arquitetural**: Gamifica o engajamento do usuário por meio de conquistas. Fornece visibilidade e reconhecimento para atividades dos usuários.

**Referência de API**: [Badges API](https://github.com/decentraland/docs/blob/main/apis/badges/overview/README.md)

### API de Recompensas

**Propósito**: Distribuição de recompensas NFT baseada em campanhas

Gerencia campanhas promocionais de recompensas NFT:

* **Gestão de campanhas** - Programas de recompensa com tempo limitado
* **Verificação de elegibilidade** - Verifica qualificação do usuário
* **Coordenação de airdrop** - Distribuição de NFT para usuários elegíveis
* **Analytics** - Rastreamento de participação na campanha

**Papel Arquitetural**: Habilita campanhas de marketing e aquisição de usuários por meio de recompensas em NFT.

**Referência de API**: [API de Recompensas](https://github.com/decentraland/docs/blob/main/apis/rewards/overview/README.md)

### Notifications Workers

**Propósito**: Sistema de entrega de notificações ao usuário

Infraestrutura de notificações multicanal:

* **Notificações in-app** - Consultas da caixa de entrada de notificações
* **Notificações por email** - Integração com SendGrid
* **Push notifications** - Alertas para mobile e desktop
* **Rastreamento de status de leitura** - Marcar notificações como lidas/não lidas

**Componentes da Arquitetura**:

* **Inbox de Notificações** - API para consultar notificações do usuário
* **Processor de Notificações** - Gera notificações a partir do Events Notifier

**Papel Arquitetural**: Mantém usuários engajados por meio de alertas oportunos sobre atividade de amigos, eventos, recompensas e atualizações do sistema.

**Referência de API**: [Notifications Workers API](https://github.com/decentraland/docs/blob/main/apis/notifications-workers/overview/README.md)

### Events Notifier

**Propósito**: Barramento de eventos para eventos da plataforma

Sistema centralizado de publicação de eventos que aciona ações downstream:

* **Eventos de usuário** - Login, compras, deployments
* **Eventos mundiais** - Atualizações de scene, ações de admin
* **Eventos do sistema** - Manutenção, atualizações

**Papel Arquitetural**: Desacopla produtores de eventos de consumidores. Serviços publicam eventos sem saber quem os processa, possibilitando arquiteturas extensíveis.

**Integrações Downstream**:

* Processor de Notificações - Cria notificações de usuário
* Processor de Badges - Concede badges de conquista
* Rewards API - Rastrea elegibilidade de campanhas

**Referência de API**: [Events Notifier API](https://github.com/decentraland/docs/blob/main/apis/events-notifier/overview/README.md)

***

## Padrões de Interação entre Serviços

### Padrões comuns de integração

#### Biblioteca Catalyst Client

Muitos serviços backend usam o **Catalyst Client** library para interagir com a rede descentralizada Catalyst:

* **Serviço Social** - Busca dados de profile do usuário
* **Events API** - Consulta metadados de scene
* **Places** - Agrega informações de scene
* **Registro de Pacotes de Assets** - Escuta eventos de deployment

Esta library abstrai a lógica de consulta multi-nó e failover.

#### Broker de Mensagens NATS

Atualizações em tempo real e comunicação assíncrona fluem através do NATS:

* **Serviço Social** - Publica mudanças de status de amigos
* **Worlds** - Transmite atualizações de configuração de world
* **Archipelago** - Roteia atualizações de posição entre ilhas
* **Events Notifier** - Publica eventos da plataforma

NATS permite que serviços se comuniquem sem acoplamento direto.

#### Indexadores de Blockchain

Serviços consultam indexadores (não a blockchain diretamente) para desempenho:

* **Worlds** - Verifica propriedade de NAME NFT
* **Atlas** - Busca dados de parcelas LAND
* **Credits Server** - Verifica saldos de token
* **API de Recompensas** - Verifica condições de elegibilidade

Consultas diretas na blockchain seriam muito lentas para APIs em tempo real.

### Pipeline de Deployment de Conteúdo

Quando um usuário faz deployment de conteúdo no Catalyst, múltiplos serviços downstream processam-no:

{% @mermaid/diagram content="flowchart TB
Deploy\[User Deploys Content]
Catalyst\[Catalyst Node]
Queue\[Deployment Queue]

```
subgraph Processing
    AB[Asset Bundle Converter]
    Profile[Profile Image Generator]
    Badges[Badges Processor]
    Events[Events Notifier]
end

Deploy --> Catalyst
Catalyst --> Queue
Queue --> AB
Queue --> Profile
Queue --> Events
Events --> Badges" %}
```

**Etapas do Pipeline**:

1. **Catalyst** - Armazena dados brutos de entidades
2. **Fila de Deployment** - Aciona processamento assíncrono
3. **Conversor de Bundle de Ativos** - Constrói bundles Unity otimizados
4. **Gerador de Imagem de Profile** - Renderiza thumbnails de avatar (para entidades de profile)
5. **Events Notifier** - Publica evento de deployment
6. **Processador de Badges** - Verifica badges de conquista por deployment

### Matriz de Dependência de Serviços

| Serviço                       | Dependências Centrais        | Fornece Dados Para             |
| ----------------------------- | ---------------------------- | ------------------------------ |
| Catalyst                      | Nenhum (decentralized)       | Todos os serviços              |
| Realm Provider                | Catalyst, Archipelago Stats  | Todos os clientes              |
| Auth Server                   | Nenhum                       | Todos os serviços protegidos   |
| Archipelago Workers           | NATS, LiveKit                | Realm Provider, Places         |
| Comms Gatekeeper              | LiveKit, Worlds API          | Clientes (geração de tokens)   |
| Worlds                        | Catalyst, NATS, Blockchain   | Gatekeeper, Clientes           |
| Serviço Social                | Catalyst, NATS, Archipelago  | Clientes                       |
| Places                        | Catalyst, Archipelago, Comms | Clientes                       |
| Events Notifier               | Nenhum                       | Notifications, Badges, Rewards |
| Registro de Pacotes de Assets | Catalyst, Deployment Queue   | Clientes (assets otimizados)   |
| Notifications Workers         | Events Notifier, SendGrid    | Clientes                       |

***

## Documentação Relacionada

### Arquitetura

* [Visão geral da arquitetura](https://docs.decentraland.org/contributor/contributor-pt/arquitetura/architecture) - Arquitetura completa do sistema
* [Catalyst Network](https://docs.decentraland.org/contributor/contributor-pt/arquitetura/catalyst) - Entrega de conteúdo descentralizada
* [Infraestrutura](https://docs.decentraland.org/contributor/contributor-pt/arquitetura/infrastructure) - Sistemas de suporte (NATS, LiveKit, databases)

### Referências de API

* [Documentação da API](https://github.com/decentraland/docs/blob/main/apis/README.md) - Especificações completas de API
* [Autenticação](https://github.com/decentraland/docs/blob/main/contributor/auth/authchain.md) - Fluxos de auth baseados em wallet
* [Comunicações](https://github.com/decentraland/docs/blob/main/contributor/comms/overview.md) - Protocolos de mensagem em tempo real

### Desenvolvimento

* [Guias para contribuintes](https://github.com/decentraland/docs/blob/main/contributor/contributor-guides/overview.md) - Workflows de desenvolvimento
* [Guia de Testes](https://github.com/decentraland/docs/blob/main/contributor/practice/testing.md) - Práticas de teste de serviços