Builder Server

Backend service for the Decentraland Builder application. Exposes endpoints for managing scene projects, wearable/emote collections, asset packs, and more.

Table of Contents

• Features
• Dependencies & Related Services
• API Documentation
• Database
  • Schema
  • Migrations
• Getting Started
  • Prerequisites
  • Installation
  • Configuration
  • Running the Service
• S3 Storage Structure
• Testing
• AI Agent Context

Features

• Scene Projects: Create, manage, and deploy scene projects to Decentraland parcels
• Collections & Items: Manage wearable and emote collections with full curation workflow
• Asset Packs: Create and manage reusable 3D asset packs for scene building
• Pools & Pool Groups: Public scene pools for community sharing and categorization
• Third Party Integration: Support for third-party wearable and emote collections
• S3 Storage: Manage project files, thumbnails, and content through S3-compatible storage
• Curation Workflow: Full approval workflow for collections and items with committee review
• Forum Integration: Automatic forum post creation for collection submissions

Dependencies & Related Services

This service interacts with the following services:

• Decentraland Builder: Frontend application that consumes this API
• Catalyst: Content server for deployed scenes and wearables
• Subgraph APIs: Blockchain data for collections, items, and third parties
• PostgreSQL: Primary database for all service data
• AWS S3 / MinIO: Object storage for projects, assets, and content files
• Discourse Forum API: Forum integration for collection submissions
• Decentraland Graph APIs: Collection, item, and third-party blockchain data

API Documentation

The API is fully documented using the OpenAPI standard. The schema is located at docs/openapi.yaml.

S3 Rewrites

The following endpoints proxy requests to S3 storage:

• GET /v1/storage/assetPacks/:filename → Asset pack thumbnails (:id.png)
• GET /v1/storage/contents/:hash → Content files by hash

Authenticated S3 Endpoints

These endpoints require authentication:

• GET /v1/projects/:id/manifest → Project manifest JSON
• GET /v1/pools/:id/manifest → Pool manifest JSON
• GET /v1/projects/:id/media/:filename → Project media files

Note: /v1/ corresponds to the version specified in .env with API_VERSION

Database

Schema

See docs/database-schemas.md for detailed schema, column definitions, and relationships.

Migrations

The service uses node-pg-migrate for database migrations. These migrations are located in migrations/.

Create a new migration

Migrations are created by running the create command:

npm run migrate -- create name-of-the-migration

This will create a migration file inside the migrations/ directory containing the migration setup and rollback procedures.

Manually applying migrations

To run migrations manually:

npm run migrate up

To rollback migrations manually:

npm run migrate down

Getting Started

Prerequisites

Before running this service, ensure you have the following installed:

• Node.js: Check .nvmrc for the required version
• npm: Comes with Node.js
• PostgreSQL: Version 12.x or higher
• Docker: For containerized external services (optional)

Installation

1. Clone the repository:

git clone https://github.com/decentraland/builder-server.git
cd builder-server

2. Install dependencies:

npm install

3. Build the project:

npm run build

Configuration

The service uses environment variables for configuration. Create a .env file in the root directory based on .env.example:

cp .env.example .env

See .env.example for all available configuration options with descriptions.

Running the Service

Using Docker Compose (Recommended for Development)

This repository provides a docker-compose.yml file to run external dependencies locally:

docker-compose up -d

This starts:

• PostgreSQL on port 5432
• Adminer (database UI) on http://localhost:8080
• MinIO (S3-compatible storage) on port 9000
• MinIO Console on http://localhost:9001

Configure your .env for Docker Compose:

CONNECTION_STRING='postgres://admin:password@localhost:5432/builder-server'
AWS_ACCESS_KEY=admin
AWS_ACCESS_SECRET=password
AWS_BUCKET_NAME=builder-server
AWS_STORAGE_URL=http://localhost:9000

First-time Setup

# Run database migrations
npm run migrate up

# Seed initial data (only once, after asset pack changes)
npm run seed

# Optional: Run one-time scripts
npx ts-node ./scripts/parseS3Pools.ts
npx ts-node ./scripts/updateProjectThumbnails.ts

Running in Development Mode

npm start

Or with auto-reload:

npm run watch:start

S3 Storage Structure

projects/
├── PROJECT_ID/
│   ├── manifest.json
│   ├── pool.json
│   ├── east.png
│   ├── north.png
│   ├── preview.png
│   ├── south.png
│   ├── thumbnail.png
│   └── west.png
asset_packs/
└── ASSET_PACK_ID.png
contents/
├── HASH1
├── HASH2
└── HASH3

Testing

This service includes test coverage with unit and integration tests.

Running Tests

Run all tests:

npm test

Run tests in watch mode:

npm run test:watch

Run tests with coverage:

npm run test:coverage

For detailed testing guidelines and standards, refer to the Decentraland Testing Standards.

AI Agent Context

For detailed AI Agent context, see docs/ai-agent-context.md.

---

License: Apache-2.0