Skip to main content
This guide provides the standards and patterns for contributing to the Worlds platform. See the Architecture page for a high-level overview of the system design.

​
Resource pattern

The Worlds Platform follows a consistent directory structure for implementing resources and services within the core and world-specific database scopes.

​
Directory structure

Each resource resides within the internal database service directories and contains:
  • queries.sql: DDL and CRUD operations.
  • queries.sql.ts: Generated string constants for SQL queries (run deno task generate).
  • schema.ts: Zod schemas for the resource.
  • service.ts: Service class implementation.
  • service.test.ts: Deno tests using in-memory database clients.

​
Implementation checklist

Follow this checklist when adding new resources, tables, or routes:
  • Create the database resource directory.
  • Add queries.sql with DDL and CRUD operations.
  • Run deno task generate to update SQL embedder files.
  • Create schema.ts and service.ts.
  • Register the table in the database initialization service.
  • Implement unit tests in service.test.ts.
  • Add DDL to the resource’s queries.sql file. - [ ] Register the table in the world-scope portion of initializeDatabase. - [ ] Verify DatabaseManager implementations execute this initialization.
  • Create routes/v1/.../route.ts.
  • Implement a default export returning a Router instance.
  • Register the module path in the server configuration.
  • Implement authentication, validation, and error handling.
  • Add integration tests in route.test.ts.

​
Routing and API

The platform uses a modular routing system, listing available modules in the server configuration.

​
Route handler pattern

Every route handler follows a consistent execution pattern:
  1. Path parameters: Read parameters from ctx.params.
  2. Authentication: Call authorizeRequest to verify identity.
  3. Validation: Parse and validate the request body or query via Zod.
  4. Business logic: Distribute work to services or resolve a world database client.
  5. Response: Return success via Response.json(record) or an ErrorResponse.

​
Testing framework

The platform utilizes a structured testing framework to ensure component reliability.

​
TestContext

The TestContext provided by the testing utilities module provides an isolated environment:
  • Isolated main database: Builds an in-memory main client for each session.
  • Schema initialization: Automatically initializes the database schema.
  • Memory database management: Uses MemoryDatabaseManager for fresh in-memory world databases.

​
Testing patterns

  • Service tests: Verify individual resource services by performing assertions on CRUD operations.
  • Route tests: Verify API endpoints by executing requests using app.fetch() with a mock Request.
  • Identity mocking: Use createTestOrganization(context) to insert a mock organization and obtain a valid API key.