Morphir

Morphir Moonbit Architecture

Overview

This repository implements Morphir in Moonbit, organized as a monorepo with multiple interdependent packages. The architecture is designed to support both server-side (WASI) and browser-based (WASM-GC) WebAssembly targets.

Repository Structure

morphir-moonbit/
├── .config/mise/              # Development tooling configuration
│   ├── config.toml           # Tool versions and environment
│   └── tasks/                # Build, test, and lint tasks
├── .github/
│   └── workflows/            # CI/CD pipelines
├── docs/                     # Documentation
├── pkgs/                     # Moonbit packages (workspace member modules)
│   ├── morphir-sdk/
│   │   ├── moon.mod         # Module definition
│   │   └── moon.pkg         # Package definition
│   ├── morphir-core/
│   │   ├── moon.mod         # Module definition
│   │   └── moon.pkg         # Package definition
│   └── morphir-moonbit-bindings/
│       ├── moon.mod         # Module definition
│       └── moon.pkg         # Package definition
├── moon.mod                  # Root module configuration
└── moon.work                 # Workspace manifest (member modules)

Note: Each package in pkgs/ is a Moonbit module with its own moon.mod (module definition) and moon.pkg (package definition within that module). The root moon.work registers each module as a workspace member so they can depend on one another from source, without a registry round-trip.

Package Organization

morphir-core

Purpose: Core abstractions and fundamental types for the Morphir ecosystem.

Responsibilities:

  • Define core types and interfaces
  • Provide fundamental abstractions
  • Establish type system foundations
  • Define IR (Intermediate Representation) structures

Dependencies: None (foundational package)

morphir-sdk

Purpose: Standard library providing functional programming primitives and data structures.

Responsibilities:

  • Implement common data structures (List, Dict, Set, etc.)
  • Provide functional utilities (map, filter, fold, etc.)
  • Define standard types and interfaces
  • Supply helper functions for common operations

Dependencies: morphir-core

morphir-moonbit-bindings

Purpose: Foreign Function Interface (FFI) bindings for Moonbit WASM targets.

Responsibilities:

  • Provide JavaScript interop for browser target
  • Define WASI bindings for server-side target
  • Expose platform-specific APIs
  • Handle serialization/deserialization across boundaries

Dependencies: morphir-core, morphir-sdk

Build Targets

WASI Target (wasm)

  • Use Case: Server-side applications, CLI tools, and WASI runtimes
  • Runtime: WasmEdge, Wasmtime, or any WASI-compliant runtime
  • Features: File system access, network I/O, system calls via WASI

Browser Target (wasm-gc)

  • Use Case: Browser-based applications
  • Runtime: Modern browsers with WASM-GC support
  • Features: JavaScript interop, DOM access, optimized GC integration

Development Workflow

Task Orchestration

All development tasks are managed through mise (formerly rtx), which provides:

  1. Consistent tooling: Same tool versions across all developers
  2. Cross-platform support: Tasks work on Linux, macOS, and Windows
  3. Simple interface: Single command to run any task
  4. Environment management: Automatic tool installation and PATH setup

Task Categories

  1. Linting: Code quality checks (YAML, Moonbit formatting)
  2. Formatting: Automatic code formatting
  3. Building: Compilation for different targets
  4. Testing: Unit and integration tests
  5. Cleaning: Remove build artifacts

CI/CD Pipeline

Parallel Execution Strategy

The CI pipeline is optimized for fast feedback:

┌─────────┐  ┌──────────────┐
│  Lint   │  │ Format Check │
└────┬────┘  └──────┬───────┘
     │              │
     └──────┬───────┘
            │
     ┌──────▼───────┐
     │   Test       │
     └──────┬───────┘
            │
     ┌──────▼───────┐
     │   Build      │
     │  (Matrix)    │
     │ - WASI       │
     │ - Browser    │
     └──────────────┘

Job Descriptions

  1. Lint Job: Validates YAML files and checks for common issues
  2. Format Check Job: Ensures code follows formatting standards
  3. Test Job: Runs all package tests
  4. Build Job: Builds all packages for both targets (matrix strategy)

Package Dependencies

┌──────────────────────┐
│   morphir-core       │  (No dependencies)
└──────────┬───────────┘
           │
           ▼
┌──────────────────────┐
│   morphir-sdk        │  (Depends on: core)
└──────────┬───────────┘
           │
           ▼
┌──────────────────────┐
│ morphir-moonbit-     │  (Depends on: core, sdk)
│     bindings         │
└──────────────────────┘

Tool Stack

Development Tools (Managed by mise)

  • Moonbit: Primary programming language
  • Bun: Fast JavaScript runtime for scripting
  • yamllint: YAML validation
  • uv: Python package management

MoonBit libraries

Our MoonBit toolchain includes these foundational libraries. This is a non-exhaustive overview; individual modules declare the dependencies they need.

Library Role
moonbitlang/core Standard library for collections, strings, numbers, JSON and other shared functionality.
moonbitlang/x Experimental and extension packages that complement the standard library.
moonbitlang/async Asynchronous I/O and structured concurrency for tooling, including filesystem operations, subprocesses and task orchestration.

Async support is included in our tooling architecture, especially the CLI and engine/pipeline host layers that process workspaces, projects, directories and files. Use moonbitlang/async where the selected package and target support the required operations. Keep target-specific I/O in host adapters so shared IR and transformation logic can run across our supported targets.

CI/CD

  • GitHub Actions: Continuous integration
  • mise-action: Tool installation in CI

Design Principles

  1. Minimal Dependencies: Each package has only necessary dependencies
  2. Target Flexibility: All packages support multiple WASM targets
  3. Task Consistency: Same commands work locally and in CI
  4. Cross-Platform: Works on Linux, macOS, and Windows
  5. Fast Feedback: Parallel CI jobs for quick iteration

Future Considerations

Planned Additions

  1. morphir-elm-interop: Interoperability with Elm implementations
  2. morphir-tooling: Development tools and utilities
  3. morphir-examples: Example applications and tutorials

Scalability

The monorepo structure allows for:

  • Easy addition of new packages
  • Shared tooling and configuration
  • Consistent versioning across packages
  • Simplified dependency management

References

IR transformation and execution

morphir-ir owns the current model, explicit v1–v4 models, codecs and migrations. morphir-scheme supplies the embeddable language, functional Scheme frontend, IR backend and runtime support. morphir-engine orchestrates files, directories, projects and workspaces using host-provided I/O and Scheme configuration.

Host → Engine → Frontend → Current IR → Script transforms → Backend → Artifacts
                             ↓
                      Scheme execution

The engine returns artifacts and stage diagnostics. Each source produces an independent artifact. morphir-host supplies memory, native, Node, WASI and WASM-GC adapters, snapshot preparation and recoverable task publication. Cross-file linking remains separate compiler work. See Morphir Engine and Morphir Scheme for APIs, executable examples and the supported language boundary.

View source on GitHub