Platform

The Orbital Platform is a composable application engine built on NATS JetStream. It provides the foundation for building applications declaratively through Ørbs.

Think of Orbital like Kubernetes: a platform that starts empty but gains capabilities as handlers register themselves. You then compose applications by applying Ørb specs.

Architecture

┌─────────────────────────────────────────────────────┐
│  Orbital Platform (monolith)                        │
│  ┌─────────────────────────────────────────────┐    │
│  │  Core Engine (internal/platform/core)        │    │
│  │  - Ørb/Module/Schema/Entry primitives       │    │
│  │  - Handler registry + dynamic routing       │    │
│  │  - Auto-CRUD from schemas                   │    │
│  │  - JetStream event sourcing                 │    │
│  └─────────────────────────────────────────────┘    │
│  ┌─────────────────────────────────────────────┐    │
│  │  Built-in Handlers                           │    │
│  │  - auth.*      (passkey, sessions)          │    │
│  │  - games.*     (launch, sync, RTP)          │    │
│  │  - payments.*  (deposit, withdraw)          │    │
│  │  - accounts.*  (register, profile)          │    │
│  └─────────────────────────────────────────────┘    │
└─────────────────────────────────────────────────────┘
                     │ NATS RPC (optional)
        ┌────────────┼────────────┐
        ▼            ▼            ▼
   ┌─────────┐  ┌─────────┐  ┌─────────┐
   │ Custom  │  │ Special │  │ 3rd Pty │    ← Extensions (via NATS)
   │ Handler │  │Provider │  │ Integr. │
   └─────────┘  └─────────┘  └─────────┘

Monolith-first architecture:

• All core capabilities are built into Orbital
• Single deployment, simple operations
• Extensions can register via NATS RPC without code changes

Key Principles

• Ørbs are domain DATA - Schemas, entries, content you manage in backoffice
• Handlers are OPERATIONS - Custom logic, integrations, flows
• Ørbs declare what they USE - Services are orb-agnostic, routes are orb-prefixed
• Event-sourced - Complete revision history via JetStream
• Schema-driven - Declarative structure, auto-generated UI
• Loosely coupled - Handlers self-register, orbs compose them

Building Blocks

Kind	Purpose	Example
Orb	Application container	games, payments, access
Module	Feature module	catalog, providers, settings
Schema	Data structure	game, provider, transaction
Entry	Content instance	Auto-generated ID

Module Types

Type	Purpose
CONTENT	Translatable content entries (games, pages, banners)
CONFIG	Configuration data, market-specific but not translatable
RULES	Business rules (evaluation engine)
TRANSACTIONS	Transaction records and audit logs
SETTINGS	Application and user preferences

Service Binding (uses)

Orbs declare which service handlers they use via uses. Routes are generated at /api/{orbId}/{handler}:

id: casino
uses:
  - service: auth
    handlers: [signup, login, logout]
  - service: games
    handlers: [launch, getSession]
  - service: payments
    handlers: [deposit, withdraw]

Generated routes:

POST /api/casino/signup    → auth.signup   (orbId: casino)
POST /api/casino/login     → auth.login    (orbId: casino)
POST /api/casino/launch    → games.launch  (orbId: casino)
POST /api/casino/deposit   → payments.deposit (orbId: casino)

The handler receives orbId in the request and can:

• Read orb-specific config (session TTL, allowed methods)
• Write to orb-specific streams (sessions, audit logs)
• Apply orb-specific business rules

Orb Definition

Orbs define domain data with schemas and field attributes:

id: games
uses:
  - service: games
    handlers: [launch, getSession, syncCatalog]

modules:
  - id: catalog
    type: CONTENT
    schemas:
      - id: game
        fields:
          - name: title
            type: string
            translatable: true
          - name: providerId
            type: reference
            ref: games/providers/provider
          - name: rtp
            type: number
          - name: enabled
            type: boolean
            marketSpecific: true

  - id: providers
    type: CONFIG
    schemas:
      - id: provider
        fields:
          - name: name
            type: string
          - name: apiKey
            type: string
            sensitive: true

Field Attributes

Attribute	Purpose
translatable	Entry can be translated per language
marketSpecific	Entry can vary per market
sensitive	Encrypted at rest, masked in UI
ref	Links to another schema for dropdowns
enum	Allowed values list
unique	Must be unique across entries
default	Default value

API Routes

The platform exposes three API groups:

Prefix	Purpose
/api/admin/	Platform Management API (orbs, modules, schemas, entries)
/api/{orbId}/	Runtime API (dynamic routes from published orbs)
/api/openapi, /api/discovery	API Discovery (public)

Reserved Orb IDs

These IDs cannot be used as orb names (they conflict with platform routes):

• admin - Platform management
• openapi - OpenAPI spec
• discovery - API discovery
• health - Health checks
• metrics - Prometheus/OTEL

Platform Management API (/api/admin/)

Administrative endpoints for managing platform resources. Requires platform_admin role.

The Management API follows a document-oriented design:

• Structure (orbs/modules/schemas) = single document, atomic updates
• Content (entries) = granular CRUD, high volume

/api/admin/
├── registry[/{service}]      # Handler registry discovery
├── routes                    # Active route listing
├── orbs/                     # Orb CRUD (document-oriented)
│   └── {orbId}/
│       ├── publish           # Publish orb
│       ├── revisions[/{v}]   # Revision history
│       └── entries/          # Entry CRUD (granular)
│           └── {entryId}/
│               ├── publish   # Publish entry
│               └── revisions # Entry revisions

Structure Endpoints (Document-Oriented)

Method	Path	Description
GET	/api/admin/orbs	List all orbs
POST	/api/admin/orbs	Create orb (full document with modules/schemas)
GET	/api/admin/orbs/{id}	Get orb with all modules and schemas
PUT	/api/admin/orbs/{id}	Update orb (full document, server diffs)
DELETE	/api/admin/orbs/{id}	Delete orb and all content
POST	/api/admin/orbs/{id}/publish	Publish orb
GET	/api/admin/orbs/{id}/revisions	List revisions
GET	/api/admin/orbs/{id}/revisions/{v}	Get specific revision

Content Endpoints (Granular)

Method	Path	Description
GET	/api/admin/orbs/{id}/entries	List entries (filter: ?module=&schema=)
POST	/api/admin/orbs/{id}/entries	Create entry (module/schema in body)
GET	/api/admin/orbs/{id}/entries/{eid}	Get entry
PUT	/api/admin/orbs/{id}/entries/{eid}	Update entry
DELETE	/api/admin/orbs/{id}/entries/{eid}	Delete entry
POST	/api/admin/orbs/{id}/entries/{eid}/publish	Publish entry
GET	/api/admin/orbs/{id}/entries/{eid}/revisions	Entry revisions

Discovery Endpoints

Method	Path	Description
GET	/api/admin/registry	List all registered handlers
GET	/api/admin/registry/{service}	Get handlers for specific service
GET	/api/admin/routes	List active routes

Runtime API (/api/{orbId}/)

Routes generated dynamically from published orbs:

/api/
├── openapi                # OpenAPI 3.0 spec (all routes)
├── discovery              # API discovery info
├── {orbId}/
│   ├── call/{handler}     # Service handlers (from uses)
│   └── {moduleId}/
│       └── {schemaId}/    # Auto-CRUD (multi-schema modules)
│           └── {id}/      # Entry operations

Auto-Generated CRUD Routes

Each CONTENT/CONFIG module automatically gets CRUD routes:

Method	Path	Description
GET	/api/{orbId}/{moduleId}/{schemaId}	List entries
GET	/api/{orbId}/{moduleId}/{schemaId}/{id}	Get entry
POST	/api/{orbId}/{moduleId}/{schemaId}	Create entry
PUT	/api/{orbId}/{moduleId}/{schemaId}/{id}	Update entry
DELETE	/api/{orbId}/{moduleId}/{schemaId}/{id}	Delete entry
POST	/api/{orbId}/{moduleId}/{schemaId}/{id}/publish	Publish entry
POST	/api/{orbId}/{moduleId}/{schemaId}/{id}/archive	Archive entry

Smart routing for single-schema modules: When a module has only one schema, the schemaId is omitted:

GET    /api/games/catalog/game           # Multi-schema: includes schemaId
GET    /api/accounts/operators           # Single-schema: schemaId omitted

Discovery Endpoints

Method	Path	Description
GET	/api/openapi	OpenAPI 3.0 spec (all Management + Runtime routes)
GET	/api/discovery	Quick overview of available orbs, modules, schemas

Handler Registry

Handlers self-register and are auto-discovered. They’re exposed as API endpoints automatically.

Registration Types

Type	Description	Use Case
Local	In-process handler function	Built-in capabilities
NATS	Remote handler via NATS RPC	Extensions, microservices
HTTP	Native HTTP handler	WebAuthn, OAuth flows

// Local handler (in-process)
core.RegisterLocal("games.launch", launchHandler, core.HandlerSpec{
    Description: "Launch a game session",
    Auth:        core.AuthRequired,
})

// NATS RPC handler (remote service)
core.RegisterNATS("payments.deposit", "orbital.payments.deposit", core.HandlerSpec{
    Description: "Process a deposit",
    Auth:        core.AuthRequired,
})

Discovery

# CLI
orbital registry list           # List all registered handlers
orbital registry get games      # Handlers for games service

# API
GET /api/admin/registry          # All handlers
GET /api/admin/registry/games    # Filter by service
GET /api/openapi                 # OpenAPI 3.0 spec
GET /api/discovery               # Quick API overview

Extension Architecture

Orbital is a monolith with extension points. External services can register handlers via NATS:

┌─────────────┐     NATS RPC      ┌──────────────┐
│   Orbital   │ ◄───────────────► │ Payment Svc  │
│  (platform) │                   │  (extends)   │
└─────────────┘                   └──────────────┘
       │                                 │
       └─── orbital.payments.* ──────────┘

To extend Orbital:

1. Create a service that connects to NATS
2. Subscribe to handler subjects (e.g., orbital.payments.process)
3. Register with Orbital’s registry (or let Orbital discover via NATS Micro)
4. Handlers are automatically available to orbs

This allows:

• Custom integrations without modifying Orbital
• Third-party provider integrations
• Specialized processing (ML, analytics)

Lifecycle

SAVED → PUBLISHED → UNPUBLISHED → ARCHIVED

• SAVED: Draft state, not visible
• PUBLISHED: Live, routes active
• UNPUBLISHED: Offline, routes removed
• ARCHIVED: Soft-deleted

CLI Quick Reference

orbital serve              # Start platform
orbital serve --legacy     # Start with legacy orchestrators

orbital orb ls             # List orbs
orbital orb get myapp      # Get orb
orbital orb apply -f x.yaml  # Apply config
orbital orb pub myapp      # Publish

Package Structure

internal/platform/core/
├── item.go              # Core Item type (Orb/Module/Schema/Entry) + ReservedOrbIDs
├── manager.go           # NATS JetStream storage
├── router.go            # Dynamic route engine
├── registry.go          # Handler registry
├── reconciler.go        # Stream/route synchronization
├── service.go           # Business logic layer
├── middleware.go        # Middleware types and registration
├── middleware_builtin.go  # logging middleware
├── system.go            # Built-in system handlers
├── mgmt_handlers.go     # Management API router (/api/admin/)
├── handlers_orbs.go     # Orb CRUD handlers
├── handlers_modules.go  # Module CRUD handlers
├── handlers_schemas.go  # Schema CRUD handlers
├── handlers_entries.go  # Entry CRUD handlers
├── runtime_handlers.go  # Runtime API handlers (/api/{orbId}/)
├── openapi.go           # OpenAPI spec generation + discovery
└── rpc.go               # RPC request/response types

Dependencies

The core engine (internal/platform/core) has minimal dependencies:

Package	Purpose
internal/platform/gravity	NATS query engine
internal/platform/httpx	HTTP utilities
internal/platform/logger	Structured logging

No database dependency - all state is in NATS JetStream.

Implementation Status

✅ Implemented

• Ørb/Module/Schema/Entry primitives
• Handler registry (Local, NATS, HTTP)
• Service binding (uses) with route generation
• Auto-CRUD routes from schemas
• JetStream event sourcing with revisions
• Middleware system (JWT, roles, logging)
• CLI commands (serve, orb ls/get/apply/pub)
• Management API (/api/admin/)
• Runtime API (/api/{orbId}/)
• API Discovery (/api/openapi, /api/discovery)
• Reserved orb IDs validation
• Field attributes (translatable, marketSpecific, sensitive, ref, etc.)
• ChangeLog with diff generation

🚧 Planned

• Scheduler service for validFrom/validTo
• Rule evaluation engine for RULES modules
• NATS Micro auto-discovery for extensions

See TODO.md for details.

NATS Stream Organization

Platform Stream (Global Configuration)

The orbital stream stores platform-level configuration and definitions:

Stream Name	Purpose	Subject Pattern	Examples
orbital	Platform configuration & definitions	orbital.*	orbital.orbs.* orbital.definitions.messages.* orbital.definitions.modules.*

Orb Streams (Per-Orb Data)

Each Ørb gets its own stream with ø-prefix naming:

Orb Name	Stream Name	Subject Pattern	Example Subjects
accounts	øaccounts	accounts.{module}.{role}.{schema}.{id}	accounts.content.admin.users.abc123 accounts.config.owner.plans.def456
payments	øpayments	payments.{module}.{role}.{schema}.{id}	payments.transactions.user.invoices.xyz789 payments.config.admin.gateways.pay001
games	øgames	games.{module}.{role}.{schema}.{id}	games.content.public.catalog.game123 games.rules.admin.leaderboards.lb001
game-platform	øgame-platform	game-platform.{module}.{role}.{schema}.{id}	game-platform.content.user.saves.save456 game-platform.settings.admin.features.feat789

Subject Components:

• {module}: Module type - content, config, rules, transactions, settings
• {role}: Access role - owner, admin, user, public
• {schema}: Schema name (kebab-case)
• {id}: Entry ID (xid format)