A typed, asynchronous bridge between a UI and its business models, in C++23.
You write a model as plain, single-threaded C++. You call it from the UI and get the result back on the UI thread. morph handles the threading, serialisation and transport, and the call site is the same whether the model runs in this process or on a server across a WebSocket.
New here?
docs/GETTING-STARTED.mdbuilds a small app end to end, first in-process and then over a socket.
A model and its actions are ordinary types:
struct Double { int x = 0; };
struct Calculator {
int execute(const Double& a) { return a.x * 2; }
};Register them once, in the .cpp that owns the model:
#include <morph/core/registry.hpp>
BRIDGE_REGISTER_MODEL (Calculator, "Calculator")
BRIDGE_REGISTER_ACTION(Calculator, Double, "Double")Call the model from the UI:
#include <morph/core/backend.hpp>
#include <morph/core/bridge.hpp>
#include <morph/core/executor.hpp>
morph::exec::ThreadPoolExecutor pool{4}; // runs the models
morph::exec::MainThreadExecutor ui; // where results are delivered; your event loop
morph::bridge::Bridge bridge{std::make_unique<morph::backend::LocalBackend>(pool), ui};
morph::bridge::BridgeHandler<Calculator> calc{bridge, &ui};
calc.execute(Double{21})
.then ([](int result) { /* 42, on the UI thread */ })
.onError([](std::exception_ptr e) { /* also on the UI thread */ });To run the model on a server, construct the Bridge with a remote backend
instead of LocalBackend. The model, the registration and the call site do not
change. The few places where local and remote behave differently, such as
authorization and exception types, are listed in
docs/spec/core/locality.md.
Bridge: one per process. It owns the active backend and can swap it at run time, for example from offline to online. It belongs to one executor, its owner (usually the UI loop), and is constructed and used there.BridgeHandler<M>: the UI's typed handle to modelM. Create one wherever a screen needs that model, and destroy handlers before their bridge.- The callback executor (
&uiabove): every.thenand.onErrorruns there, never on a worker thread. UseMainThreadExecutorfor a plain loop ormorph::qt::QtExecutorunder Qt. - Strands: each model instance runs its actions one at a time, while different models run in parallel. Models need no locks.
Two rules that bite:
- Registration must survive the link. If your models live in a static
library, link it whole (
--whole-archive,-force_load, or CMake'sWHOLE_ARCHIVE). Otherwise the linker drops the registration and the model never registers. - A remote model must be registered and default-constructible, because the server creates instances from the registered type name.
Everything beyond the core is opt-in: include a header only when you need it.
- Server-driven screens. A server serves its screens as declarative JSON
documents (
ui/1). One generic client renders them with Qt Quick, in a terminal, or in the browser through WebAssembly. Actions declare which data they change (BRIDGE_REGISTER_EFFECTS), so every open screen on every client refreshes without the screen saying what to reload. Seedocs/KEEPING-SCREENS-CURRENT.mdanddocs/spec/ui/. - Forms from action types.
morph::formsgenerates a JSON Schema for every action, with units, precision, bounds, choices and required fields, so a client can build the form at run time. - Exact values.
morph::math::Rationalis an exact decimal fraction,morph::units::Quantity<Unit>adds compile-time unit checking (kg / m³ gives kg/m³; kg + m³ does not compile), andmorph::timehas strict ISO-8601 UTC timestamps. - Shared instances. Handlers that opt in with
AllowSharedand name the same primary key reach one model instance, across clients too. Seedocs/spec/core/shared_instances.md. - Coroutines. A client can
co_awaitaCompletion<T>, and a model's action can itself be a coroutine. - Action journal.
morph::journalkeeps an ordered, replayable record of executed actions for auditing, and supports undo by replay. - Offline support.
morph::offlineprovides connectivity monitoring, durable write queues (file or SQLite), replay on reconnect and an ordered reconnect sequence. - Sessions and authorization. A
session::Contexttravels with every call, andRemoteServerchecks each request with anIAuthorizerbefore it runs. - Transports. Qt 6 WebSockets, or a raw POSIX socket transport.
On Linux:
cmake --preset clang-release
cmake --build build/clang-release --target morph_tests
./build/clang-release/tests/morph_testsTo use morph in your own project, install it and use
find_package(morph CONFIG REQUIRED) with morph::morph.
docs/BUILDING.md covers dependencies (Glaze, core-cpp,
optional Qt), every CMake option, optional components, and vendoring.
| Example | What it shows |
|---|---|
examples/bookmarks |
The small, complete path: models, SQLite, sign-in, server-served screens, local and remote. Used by the tutorial. |
examples/bank |
A real domain: many models, money, shared instances, the offline queue, and a WebAssembly client |
examples/lims |
A large app: units, versioned forms, role-gated workflows, offline capture, the journal as an audit trail |
examples/forms |
Schema-driven forms over exact, unit-tagged lab values |
examples/concepts |
One small test per production feature: outbox, durable queue, authorization, limits, versioning, shutdown |
examples/client |
The generic client that renders every example's screens |
Bookmarks, bank and lims form the application ladder, apps of increasing size that exist to test morph rather than to ship.
- Security is up to the application. There is no built-in authentication,
and the default authorizer allows everything. Size limits, timeouts, protocol
versioning and authorization hooks exist but are opt-in. See
docs/spec/security.md. Rationalis fixed-width (int64numerator and denominator). Arithmetic that overflows saturates and logs an error; usecheckedAddand similar functions to detect overflow.- Journal replay re-executes actions, so undo is exact only for deterministic, in-memory models. Models with their own database can use the transactional outbox instead.
- Registration is global and resolved at run time. An unknown type name fails when it is called, not when it is compiled.
- No stability promise before 1.0. morph is
0.1.0. The policy that will apply from 1.0 is indocs/spec/VERSIONING.md.
docs/GETTING-STARTED.md: a tutorial that builds one app end to end.docs/ARCHITECTURE.md: layers, wire protocol, deployment topologies and the reasons behind them.docs/KEEPING-SCREENS-CURRENT.md: how screens refresh after an action, with a checklist for new actions.docs/BUILDING.md: dependencies, options, installation.docs/spec/: the authoritative design spec for each type and subsystem.CONTRIBUTING.mdandAGENTS.md: how to change morph.
Apache-2.0.