Well-Known Components

This section provides comprehensive guidelines for building services using the Well-Known Components (WKC) standard. Following these standards ensures consistency, testability, and maintainability across all Decentraland services.

Overview

Well-Known Components services are built using a modular architecture based on two main building blocks:

• Components - Reusable, testable black-box units that encapsulate functionality

• Controllers - Request handlers that manage HTTP and WebSocket communication

Component Types

We distinguish between two primary types of components:

• Adapters - Components that handle I/O processes and external integrations

• Logic Components - Components that contain business logic

Key Principles

WKC services follow these core principles:

1. Modularity - Each component is self-contained with clear interfaces

2. Testability - Components are designed to be easily unit and integration tested

3. Dependency Injection - Components receive their dependencies explicitly

4. Interchangeability - Components can be swapped with alternative implementations

5. Separation of Concerns - Business logic is separated from I/O operations

Architecture

Service
├── Components
│   ├── Adapters (I/O operations)
│   │   ├── Database adapters
│   │   ├── External API clients
│   │   └── Storage adapters
│   └── Logic (Business logic)
│       ├── Domain logic
│       └── Orchestration
└── Controllers (Transport layer)
    ├── HTTP handlers
    └── WebSocket handlers

Component Sources

Components can be imported from:

• WKC Organization - Standard WKC components

• Core Components Repository - Decentraland-specific components

Getting Started

To build a WKC-compliant service:

1. Review the Components documentation to understand component structure

2. Learn about Adapters for handling external integrations

3. Understand Logic Components for implementing business logic

4. Study Controllers for handling HTTP/WebSocket requests

Standards Compliance

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this documentation are to be interpreted as described in RFC 2119.