> For the complete documentation index, see [llms.txt](https://docs.decentraland.org/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.decentraland.org/contributor/contributor-ko/architecture/services.md).

# 백엔드 서비스

이 페이지는 모든 Decentraland 백엔드 서비스, 그 아키텍처상의 역할, 그리고 생태계 안에서 서로 어떻게 상호작용하는지에 대한 종합 개요를 제공합니다. 자세한 API 사양과 엔드포인트는 다음을 참조하세요. [API 참조](https://github.com/decentraland/docs/blob/main/apis/README.md) 섹션에서 설명한 것과 동일한 규칙을 따릅니다.

## 서비스 아키텍처

Decentraland의 백엔드는 논리적 계층으로 구성된 분산 마이크로서비스로 이루어져 있습니다:

* **분산형 계층** - Catalyst 네트워크 및 콘텐츠 전송 인프라
* **실시간 통신 계층** - 서비스 검색 및 P2P 통신
* **기능 서비스** - 사용자 대면 기능(콘텐츠, 경제, 게임화)
* **핵심 서비스** - 필수 플랫폼 인프라(인증, 마켓플레이스, 알림)

***

## 분산형 계층

### 캐털리스트

**목적**: 분산형 콘텐츠 전송 네트워크

Catalyst 네트워크는 Decentraland 콘텐츠 인프라의 기반을 이룹니다. 각 Catalyst 노드는 다음을 제공하는 완전한 서버입니다:

* **콘텐츠 서버** - 엔티티 저장 및 검색(씬, 프로필, 착용 아이템)
* **Lambdas 서비스** - 유틸리티 엔드포인트 및 콘텐츠 쿼리
* **통신 서버** - 실시간 메시지 전송

**아키텍처 역할**: Catalyst 노드는 지리적으로 분산되어 있으며 허가 없이 참여할 수 있습니다. 이 네트워크는 중앙 제어 없이 콘텐츠 중복성과 가용성을 제공합니다.

**주요 통합**:

* Realm Provider - 노드 가용성을 알림
* Asset Bundle Registry - 배포 시 자산 최적화를 트리거
* Archipelago Workers - 섬/클러스터 데이터 제공

**API 참조**: [Catalyst API](https://github.com/decentraland/docs/blob/main/apis/catalyst/overview/README.md)

### Lamb2

**목적**: Lambda 유틸리티 및 서버리스 함수

Lamb2는 Content Server를 보완하는 콘텐츠 소비 및 쿼리용 유틸리티 엔드포인트를 제공합니다:

* \- 씬 집계 및 필터링
* \- 대체 경로를 포함한 프로필 쿼리
* \- 상태 및 헬스 체크

**아키텍처 역할**: Content Server의 원시 엔티티 접근 위에 편의 계층으로 작동하며, 클라이언트가 자주 필요로 하는 더 높은 수준의 쿼리 패턴을 제공합니다.

**API 참조**: [Lamb2 API](https://github.com/decentraland/docs/blob/main/apis/lamb2/overview/README.md)

***

## 실시간 통신 계층

### Realm Provider

**목적**: 서비스 검색 및 리얼름 선택

Realm Provider는 모든 Decentraland 클라이언트의 진입점입니다. 다음을 기반으로 지능적인 리얼름 선택을 구현합니다:

* **지리적 최적화** - 사용자를 가장 가까운 Catalyst 노드로 라우팅
* **헬스 모니터링** - 비정상 또는 과부하 상태의 노드 필터링
* **용량 추적** - 리얼름별 실시간 사용자 수 제공
* **인기 씬 집계** - 모든 리얼름에서 인기 있는 위치 식별

**아키텍처 역할**: 사용 가능한 인프라의 단일 진실 원천입니다. 클라이언트는 시작 시 한 번만 이를 조회해 모든 서비스 엔드포인트(Catalyst, Comms, BFF)를 발견합니다.

**주요 통합**:

* \- 모든 Catalyst 노드를 주기적으로 폴링
* \- Archipelago 통계 집계
* \- 분산 네트워크의 통합된 뷰 제공

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

### 통신 게이트키퍼

**목적**: 음성 및 비디오 접근 제어

Gatekeeper는 음성 및 비디오 채팅을 위한 LiveKit 미디어 서버 접근을 관리합니다:

* **토큰 생성** - 특정 권한이 포함된 시간 제한 접근 토큰 생성
* **씬 관리** - 씬 관리자 권한 및 차단 관리
* **스트림 관리** - 라이브 스트리밍 접근 및 RTMP 키 제어
* **프라이버시 제어** - 비공개 음성 채팅 권한 강제

**아키텍처 역할**: 클라이언트와 미디어 인프라 사이의 보안 계층입니다. 유연한 권한 모델(씬 기반, 비공개, 커뮤니티)을 지원하면서 무단 접근을 방지합니다.

**주요 통합**:

* LiveKit - 미디어 서버 접근용 JWT 토큰 발급
* Worlds API - 관리자 권한을 위한 월드 소유권 검증
* Signed Fetch - 지갑 서명을 통해 모든 요청을 인증

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

### Archipelago Workers

**목적**: 통신 클러스터링 및 메시지 라우팅

Archipelago는 가까운 플레이어를 "섬"으로 그룹화하는 근접 기반 클러스터링 프로토콜을 구현합니다:

* **WebSocket 전송** - 클라이언트와의 지속 연결 유지
* **위치 추적** - 플레이어 위치를 실시간으로 모니터링
* **섬 형성** - 거리에 따라 플레이어를 동적으로 그룹화
* **메시지 라우팅** - 섬 구성원에게만 메시지 전달

**아키텍처 구성 요소**:

* **WebSocket 커넥터** - 클라이언트 연결 및 인증 처리
* **Archipelago Core** - 클러스터링 알고리즘 및 섬 관리를 구현
* **통계 서비스** - 연결 지표 및 사용자 수 제공
* **NATS 통합** - 위치 업데이트 게시 및 메시지 라우팅

**아키텍처 역할**: 피어 투 피어 통신을 메시지 팬아웃을 제한하여 최적화합니다. 리얼름 내의 모든 사용자에게 브로드캐스트하는 대신, 메시지는 상호작용 범위 내의 플레이어에게만 도달합니다.

**주요 통합**:

* NATS 메시지 브로커 - 분산 메시지 라우팅
* Realm Provider - 섬 통계 제공
* Places API - 핫 씬의 사용자 수 데이터

**API 참조**: [Archipelago Workers API](https://github.com/decentraland/docs/blob/main/apis/archipelago-workers/overview/README.md)

***

## 기능 서비스

### 월드

**목적**: 메인 그리드 외부의 격리된 씬 호스팅

Worlds는 사용자가 격리된 환경에 씬을 배포할 수 있게 합니다:

* **이름이 있는 월드** - 사용자 지정 URL을 통해 접근 가능(예: `world.dclworlds.com`)
* **비공개 월드** - NFT 기반 접근 제어
* **월드 권한** - 소유자가 관리하는 관리자 및 배포 권한

**아키텍처 역할**: Decentraland의 콘텐츠 모델을 고정된 LAND 그리드 너머로 확장합니다. 각 월드는 고유한 통신 채널과 접근 제어를 가진 독립적인 씬입니다.

**주요 통합**:

* NFT 소유권 검증을 위해 블록체인 인덱서에 쿼리
* 실시간 클라이언트 동기화를 위해 월드 업데이트를 NATS에 게시
* 음성 채팅방을 위해 Comms Gatekeeper와 통합
* 배포 시 자산 처리 파이프라인을 트리거

**API 참조**: [Worlds API](https://github.com/decentraland/docs/blob/main/apis/worlds/overview/README.md)

### 이벤트

**목적**: 월드 내 이벤트 관리 및 발견

가상 이벤트의 전체 수명 주기를 관리합니다:

* **이벤트 CRUD** - 생성, 업데이트, 일정 설정
* **참가자 추적** - 사용자 참여 및 RSVP
* **검색** - 시간 기반 쿼리 및 필터링
* **알림** - Events Notifier와의 통합

**아키텍처 역할**: 메타버스에 시간적 맥락을 제공합니다. 이벤트는 시간에 민감한 경험을 강조함으로써 사용자 발견과 참여를 이끕니다.

**API 참조**: [Events API](https://github.com/decentraland/docs/blob/main/apis/events/overview/README.md)

### Places

**목적**: 관심 지점 발견 및 큐레이션

Decentraland 전반의 흥미로운 위치를 집계하고 큐레이션합니다:

* **핫 씬** - 사용자 수를 기반으로 한 실시간 인기
* **추천 장소** - 편집적으로 선별된 위치
* **검색 및 필터링** - 태그, 카테고리로 발견
* **POI 메타데이터** - 설명, 썸네일, 좌표

**아키텍처 역할**: 대규모 오픈 월드에서의 발견 문제를 해결합니다. 여러 소스의 데이터를 집계해 사용자가 몰입할 만한 콘텐츠를 찾도록 돕습니다.

**주요 통합**:

* Catalyst - 씬 메타데이터 및 배포 정보
* Archipelago 통계 - 씬별 실시간 사용자 수
* Comms Gatekeeper - 리얼름 가용성 및 상태

**API 참조**: [Places API](https://github.com/decentraland/docs/blob/main/apis/places/overview/README.md)

### 아틀라스 서버

**목적**: 지도 데이터 및 파셀 시각화

포괄적인 월드 지도 데이터를 제공합니다:

* **파셀 소유권** - 블록체인 인덱싱된 LAND 데이터
* **씬 메타데이터** - 배포된 씬 이름 및 좌표
* **지도 타일** - UI 표시용 미리 렌더링된 타일 이미지
* **공간 쿼리** - 좌표 또는 소유자로 파셀 찾기

**아키텍처 역할**: Decentraland의 LAND 그리드에 대한 공간 인덱스를 제공합니다. 지도 UI와 공간 내비게이션에 필수적입니다.

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

### Camera Reel

**목적**: 사용자 생성 스크린샷 관리

사용자 스크린샷 및 이미지를 관리합니다:

* **이미지 업로드** - 인증된 이미지 저장
* **갤러리 구성** - 사용자 스크린샷 컬렉션
* **메타데이터** - 씬 위치, 타임스탬프, 태그

**아키텍처 역할**: 사용자 생성 사진을 중심으로 한 콘텐츠 공유 및 소셜 기능을 가능하게 합니다.

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

### 탐험 게임

**목적**: 온보딩 게임화 및 튜토리얼

신규 사용자 온보딩을 위한 인터랙티브 퀘스트 시스템:

* **퀘스트 추적** - 튜토리얼 미션 진행
* **도전 과제 완료** - 과제 검증
* **보상 통합** - 보상 시스템과 연결

**아키텍처 역할**: 구조화된 목표 지향적 Decentraland 기능 소개를 제공하여 신규 사용자의 진입 장벽을 낮춥니다.

**API 참조**: [탐험 게임 API](https://github.com/decentraland/docs/blob/main/apis/exploration-games/overview/README.md)

***

## 핵심 서비스

### 인증 서버

**목적**: 지갑 기반 인증 및 세션 관리

Decentraland의 지갑 우선 인증 모델을 구현합니다:

* **서명 검증** - Ethereum 지갑 서명 검증
* **JWT 토큰 발급** - 세션 토큰 생성
* **토큰 검증** - 보호된 리소스에 대한 토큰 확인
* **세션 수명 주기** - 토큰 갱신 및 만료

**아키텍처 역할**: 분산형 신원 검증을 제공합니다. 사용자는 비밀번호 대신 지갑 서명을 통해 인증하므로 Web3 원칙에 부합합니다.

**인증 흐름**:

1. 클라이언트가 챌린지 요청
2. 사용자가 지갑으로 챌린지 서명
3. Auth Server가 서명을 검증하고 JWT 발급
4. 클라이언트가 후속 API 요청에 JWT 포함

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

### 소셜 서비스

**목적**: 소셜 그래프 및 커뮤니티 관리

소셜 관계 및 커뮤니티를 관리합니다:

* **친구 시스템** - 요청, 승인, 친구 목록
* **차단 목록** - 사용자 차단 및 프라이버시
* **커뮤니티** - 그룹 멤버십 및 발견
* **실시간 상태** - NATS를 통한 친구 온라인/오프라인 알림
* **개인 메시징** - 다이렉트 메시지 인프라

**아키텍처 역할**: Decentraland를 가상 세계에서 소셜 메타버스로 바꾸는 소셜 계층을 제공합니다.

**주요 통합**:

* Catalyst Client - 친구 프로필 데이터 가져오기
* NATS - 친구 상태 업데이트 게시
* Archipelago - 온라인 상태 및 위치 조회

**API 참조**: [소셜 서비스 API](https://github.com/decentraland/docs/blob/main/apis/social-service/overview/README.md)

### 마켓플레이스 서버

**목적**: NFT 마켓플레이스 통합

Decentraland의 착용 아이템 및 이모트 마켓플레이스를 위한 백엔드:

* **리스트 쿼리** - 마켓플레이스 아이템 탐색 및 검색
* **거래 내역** - 구매 기록
* **가격 데이터** - 시장 가격 및 추세
* **컬렉션 메타데이터** - 착용 아이템 및 이모트 컬렉션

**아키텍처 역할**: 온체인 NFT 데이터를 사용자 친화적인 마켓플레이스 UI와 연결합니다. 빠른 쿼리를 위해 블록체인 이벤트를 인덱싱합니다.

**API 참조**: [마켓플레이스 서버 API](https://github.com/decentraland/docs/blob/main/apis/marketplace-server/overview/README.md)

***

## 자산 서비스

### 자산 번들 레지스트리

**목적**: 최적화된 자산 관리

플랫폼 최적화 자산 번들 저장소:

* 플랫폼별 자산 번들 URL
* 버전 관리
* CDN 배포

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

**시스템 구성 요소**:

* **자산 번들 변환기** - 플랫폼별 번들 생성
* **LOD 생성기** - 수준별 상세도 변형 생성

**프로세스 흐름**:

{% @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

**목적**: 스크린샷 및 이미지 관리

사용자 생성 콘텐츠 관리:

* 스크린샷 저장
* 이미지 업로드
* 갤러리 구성

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

### Credits Server

**목적**: 가상 화폐 및 경제

Decentraland의 가상 크레딧 시스템을 관리합니다:

* **잔액 추적** - 사용자 크레딧 잔액
* **거래 원장** - 크레딧 이체 및 지출
* **구매 통합** - 법정화폐-크레딧 전환
* **블록체인 동기화** - 온체인 잔액을 위해 인덱서 조회

**아키텍처 역할**: 인월드 구매 및 기능을 위해 블록체인 토큰보다 진입 장벽이 낮은 통화 대안을 제공합니다.

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

### 배지

**목적**: 성취 및 게임화 시스템

이벤트 기반 배지 수여:

* **배지 정의** - 사용 가능한 성취
* **사용자 인벤토리** - 사용자별 획득 배지
* **자동 지급** - 이벤트 트리거 배지 수여

**아키텍처 구성 요소**:

* **배지 API** - 배지 쿼리 및 사용자 인벤토리
* **배지 처리기** - Events Notifier를 수신하고 배지를 수여

**아키텍처 역할**: 성취를 통해 사용자 참여를 게임화합니다. 사용자 활동에 대한 가시성과 인정을 제공합니다.

**API 참조**: [배지 API](https://github.com/decentraland/docs/blob/main/apis/badges/overview/README.md)

### 보상 API

**목적**: 캠페인 기반 NFT 보상 배포

프로모션 NFT 보상 캠페인을 관리합니다:

* **캠페인 관리** - 기간 한정 보상 프로그램
* **자격 검증** - 사용자 자격 확인
* **에어드롭 조정** - 적격 사용자에게 NFT 배포
* **분석** - 캠페인 참여 추적

**아키텍처 역할**: NFT 보상을 통해 마케팅 캠페인과 사용자 확보를 가능하게 합니다.

**API 참조**: [보상 API](https://github.com/decentraland/docs/blob/main/apis/rewards/overview/README.md)

### Notifications Workers

**목적**: 사용자 알림 전달 시스템

다중 채널 알림 인프라:

* **앱 내 알림** - 알림 받은편지함 쿼리
* **이메일 알림** - SendGrid 통합
* **푸시 알림** - 모바일 및 데스크톱 알림
* **읽음 상태 추적** - 알림을 읽음/읽지 않음으로 표시

**아키텍처 구성 요소**:

* **알림 받은편지함** - 사용자 알림 조회용 API
* **Notifications Processor** - Events Notifier에서 알림 생성

**아키텍처 역할**: 친구 활동, 이벤트, 보상, 시스템 업데이트에 대한 적시 알림을 통해 사용자의 참여를 유지합니다.

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

### Events Notifier

**목적**: 플랫폼 이벤트용 이벤트 버스

후속 작업을 트리거하는 중앙 집중식 이벤트 게시 시스템:

* **사용자 이벤트** - 로그인, 구매, 배포
* **월드 이벤트** - 씬 업데이트, 관리자 작업
* **시스템 이벤트** - 유지보수, 업데이트

**아키텍처 역할**: 이벤트 생성자와 소비자를 분리합니다. 서비스는 누가 처리하는지 알지 못한 채 이벤트를 게시할 수 있어 확장 가능한 아키텍처를 가능하게 합니다.

**하위 통합**:

* Notifications Processor - 사용자 알림 생성
* Badges Processor - 성취 배지 지급
* Rewards API - 캠페인 자격 추적

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

***

## 서비스 상호작용 패턴

### 일반적인 통합 패턴

#### Catalyst Client 라이브러리

많은 백엔드 서비스가 **Catalyst Client** 라이브러리를 사용해 분산형 Catalyst 네트워크와 상호작용합니다:

* **소셜 서비스** - 사용자 프로필 데이터 가져오기
* **Events API** - 씬 메타데이터 쿼리
* **Places** - 씬 정보 집계
* **자산 번들 레지스트리** - 배포 이벤트 수신

이 라이브러리는 다중 노드 쿼리와 페일오버 로직을 추상화합니다.

#### NATS 메시지 브로커

실시간 업데이트와 비동기 통신은 NATS를 통해 흐릅니다:

* **소셜 서비스** - 친구 상태 변경 게시
* **월드** - 월드 구성 업데이트 브로드캐스트
* **Archipelago** - 섬 간 위치 업데이트 라우팅
* **Events Notifier** - 플랫폼 이벤트를 발행합니다

NATS는 서비스들이 직접적으로 결합되지 않고 통신할 수 있게 합니다.

#### 블록체인 인덱서

성능을 위해 서비스는 인덱서에 질의합니다(블록체인에 직접 질의하지 않음):

* **월드** - NAME NFT 소유권을 확인합니다
* **Atlas** - LAND 토지 구획 데이터를 가져옵니다
* **Credits Server** - 토큰 잔액을 확인합니다
* **보상 API** - 자격 조건을 확인합니다

블록체인에 직접 질의하는 것은 실시간 API에는 너무 느립니다.

### 콘텐츠 배포 파이프라인

사용자가 Catalyst에 콘텐츠를 배포하면 여러 하위 서비스가 이를 처리합니다:

{% @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" %}
```

**파이프라인 단계**:

1. **캐털리스트** - 원시 엔티티 데이터를 저장합니다
2. **배포 대기열** - 비동기 처리를 트리거합니다
3. **자산 번들 변환기** - 최적화된 Unity 번들을 빌드합니다
4. **프로필 이미지 생성기** - 아바타 썸네일을 렌더링합니다(프로필 엔티티용)
5. **Events Notifier** - 배포 이벤트를 발행합니다
6. **배지 처리기** - 배포 업적 배지를 확인합니다

### 서비스 종속성 매트릭스

| 서비스                   | 핵심 종속성                       | 데이터 제공 대상              |
| --------------------- | ---------------------------- | ---------------------- |
| 캐털리스트                 | 없음(탈중앙화)                     | 모든 서비스                 |
| Realm Provider        | Catalyst, Archipelago Stats  | 모든 클라이언트               |
| 인증 서버                 | 없음                           | 모든 보호된 서비스             |
| Archipelago Workers   | NATS, LiveKit                | Realm Provider, Places |
| 통신 게이트키퍼              | LiveKit, Worlds API          | 클라이언트(토큰 생성)           |
| 월드                    | Catalyst, NATS, 블록체인         | Gatekeeper, 클라이언트      |
| 소셜 서비스                | Catalyst, NATS, Archipelago  | 클라이언트                  |
| Places                | Catalyst, Archipelago, Comms | 클라이언트                  |
| Events Notifier       | 없음                           | 알림, 배지, 보상             |
| 자산 번들 레지스트리           | Catalyst, 배포 대기열             | 클라이언트(최적화된 에셋)         |
| Notifications Workers | Events Notifier, SendGrid    | 클라이언트                  |

***

## 관련 문서

### 아키텍처

* [아키텍처 개요](/contributor/contributor-ko/architecture/architecture.md) - 전체 시스템 아키텍처
* [Catalyst 네트워크](/contributor/contributor-ko/architecture/catalyst.md) - 탈중앙화된 콘텐츠 전송
* [인프라](/contributor/contributor-ko/architecture/infrastructure.md) - 지원 시스템(NATS, LiveKit, 데이터베이스)

### API 참조

* [API 문서](https://github.com/decentraland/docs/blob/main/apis/README.md) - 전체 API 명세
* [인증](https://github.com/decentraland/docs/blob/main/contributor/auth/authchain.md) - 지갑 기반 인증 흐름
* [통신](https://github.com/decentraland/docs/blob/main/contributor/comms/overview.md) - 실시간 메시징 프로토콜

### 개발

* [기여자 가이드](https://github.com/decentraland/docs/blob/main/contributor/contributor-guides/overview.md) - 개발 워크플로
* [테스트 가이드](https://github.com/decentraland/docs/blob/main/contributor/practice/testing.md) - 서비스 테스트 관행


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.decentraland.org/contributor/contributor-ko/architecture/services.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.