How-to › Run message-based services

How to scaffold a service system from a model file#

Scaffold a Seneca backend with create-system, grow its model with the voxgig-system CLI, and regenerate without losing the code you wrote.

Audience
Platform team
Level
beginner
Topic
Build message-based services
Languages
TypeScript
Verified

Your backend declares a shop service in its model, and a teammate writes the service’s handler by copying another one. The model lists one set of messages and the code answers another. A hand edit to the generated Lambda handler disappears at the next build, because no file in the tree says which files the build owns.

What you get

You will end up with a booted backend that answers a message the model declares, and a record of which files each regeneration rewrites. This is for you if your services are declared in a model and your team edits the files the model generates.

Short answer

Scaffold the backend with create-system, then use the voxgig-system CLI to append a service, an entity, a field, a message, and an environment to the model. Run npm run build after each command. The commands write model lines only, and the build rewrites generated files, so put each message’s action in its own file under src/srv and never edit a generated file.

You will need

Node 22, and the sample directory with npm ci run in it. The sample holds the project the steps below produced, so every command on this page runs offline against a scratch copy of it. The scaffold is a Seneca backend: every service is a set of message patterns, and @voxgig/system loads the services the model declares.

Expect three workarounds before the scaffold works, each shown below: a shape override to scaffold, a second one to build, and a model.aontu symlink for the add commands. Two more defects shape the page. The scaffold’s pinned @voxgig/model cannot move to 12.0.2, and its tutorial names a model file the scaffold does not write.

Approaches compared

ApproachWhen it fitsWhat it costs youWhen to pick something else
@voxgig/system with create-systemMessage services in Seneca, declared in one model that also generates deploy files and docsTwo shape overrides and a symlink before it builds, and a model you keep correctYour services speak HTTP to each other and the team writes NestJS
NestJS CLI schematicsA NestJS app where each controller or resource is written once and then ownedEach run writes files from its options and keeps no model, so the code drifts from any descriptionSeveral services must stay in step with one contract
NSwagASP.NET Core services generated from an OpenAPI documentYou run it under .NET, and the compiler, not a boot, reports a missing methodYour services are not .NET
Nx generatorsA monorepo that wants house conventions in every scaffoldYou write and maintain each generator, and a one-shot generator’s output is yours once it runsThe files must follow a model you edit, unless you write a sync generator for it
OpenAPI GeneratorA NestJS server whose routes come from an OpenAPI documentA beta generator, and a protected controller stops receiving the routes you addYour services exchange messages, not HTTP requests

Voxgig maintains @voxgig/system and create-system, the worked path here, and sponsors Seneca. The other four rows are maintained elsewhere.

The model route keeps services, messages and entities in one place and regenerates from it, at the price of a toolchain that needed three workarounds on the day it ran. A Nest schematic asks for no model, because each run writes its files once and then the files are yours. Nx can keep files in step through sync generators, which you write yourself. OpenAPI Generator and NSwag regenerate from a contract too, but the contract is HTTP and the services are controllers.

Scaffold the backend

The documented npm create @voxgig/system my-app failed in this run, with exit 1 and TypeError: (0 , shape_1.One) is not a function. The scaffolder pins jostraca 0.41.0, which calls a shape export that no 12.x release has. Install the scaffolder with shape held at the last 11.x release instead, through an npm override.

mkdir tool && cd tool && npm init -y && npm pkg set 'overrides.shape=11.4.1'
npm i @voxgig/create-system@0.10.3 && cd .. && ./tool/node_modules/.bin/create-system my-app

It prints Created my-app/ (36 files). The build inside backend fails the same way through @voxgig/build, so hold its jostraca’s shape too, then install and build.

cd my-app/backend && npm pkg set 'overrides.jostraca.shape=11.4.1' && npm install && npm run build && npm test

The starter tests report # pass 2. One more step: the CLI looks for model.aontu, and the scaffold writes model.aon, so every add command fails with model folder not found until you link the two.

ln -s model.aon model/model.aontu

The CLI’s extension list is ['aontu', 'jsonic'],1 and create-system’s own tutorial names model/ent.aontu.

Add a service, an entity, a field, a message, and an environment

Run the five commands in order from my-app/backend, with npm run build after each.

npx voxgig-system add srv shop && npm run build
npx voxgig-system add entity shop/product && npm run build
npx voxgig-system add field shop/product title price:Number && npm run build
npx voxgig-system add msg shop.get.product && npm run build
npx voxgig-system add env aws && npm run build

The sample’s record of each step lists what the command changed and what the build then added, rewrote, or left alone.

node steps.mjs
1. npx voxgig-system add srv shop
   the command changed: backend/model/srv.aon
   npm run build added: backend/src/handler/lambda/shop.ts
   npm run build rewrote: backend/gen/env/aws/srv.yml, backend/model/model.json, docs/reference/messages.md, docs/reference/system-map.md
   npm run build left alone: 44 files
2. npx voxgig-system add entity shop/product
   the command changed: backend/model/ent.aon
   npm run build added: none
   npm run build rewrote: backend/gen/api/openapi.json, backend/gen/api/openapi.yaml, backend/model/model.json, docs/reference/entities.md, docs/reference/system-map.md
   npm run build left alone: 44 files
3. npx voxgig-system add field shop/product title price:Number
   the command changed: backend/model/ent.aon
   npm run build added: none
   npm run build rewrote: backend/gen/api/openapi.json, backend/gen/api/openapi.yaml, backend/model/model.json, docs/reference/entities.md
   npm run build left alone: 45 files
4. npx voxgig-system add msg shop.get.product
   the command changed: backend/model/msg.aon
   npm run build added: none
   npm run build rewrote: backend/model/model.json, docs/reference/messages.md
   npm run build left alone: 47 files
5. npx voxgig-system add env aws
   the command changed: backend/model/env.aon
   npm run build added: backend/gen/env/aws/README.md, backend/gen/env/aws/serverless.yml
   npm run build rewrote: backend/model/model.json, docs/reference/system-map.md
   npm run build left alone: 47 files
6. write src/srv/shop/shop-srv.ts and src/srv/shop/get_product.ts
   written by hand: backend/src/srv/shop/get_product.ts, backend/src/srv/shop/shop-srv.ts
   npm run build added: backend/src/srv/shop/README.md
   npm run build rewrote: none
   npm run build left alone: 53 files

Two things in that record matter more than the rest. No add command wrote service code: the message step appended one line to msg.aon, and the build rewrote model.json and a generated reference page.

node steps.mjs msg
4. npx voxgig-system add msg shop.get.product
   the command changed: backend/model/msg.aon
   +aim: shop: get: product: {}
   npm run build added: none
   npm run build rewrote: backend/model/model.json, docs/reference/messages.md
   npm run build left alone: 47 files

The second is where the build writes. It added src/handler/lambda/shop.ts inside src/, beside code you own, and a README.md inside src/srv/shop/ once that folder existed. Both are generated, and the README says so in its first comment.

Write the action the message names

MakeSrv connects the model to the code. For each message the model gives the service, it loads the action file named after the message’s last pattern pair, so aim:shop,get:product loads ./get_product. That rule is actpath in system.ts.

// The shop service. MakeSrv reads the model's main.srv.shop and loads one action file per
// message it answers: aim:shop,get:product -> ./get_product.
import { MakeSrv } from '@voxgig/system'

module.exports = MakeSrv('shop', require)

The action loads the entity the model declares, through Seneca’s entity layer.

// The action for aim:shop,get:product, declared in model/msg.aon.
module.exports = function make_get_product() {
  return async function get_product(this: any, msg: any) {
    const product = await this.entity('shop/product').load$(msg.id)
    if (null == product) {
      return { ok: false, why: 'not-found' }
    }
    return { ok: true, product: { id: product.id, title: product.title, price: product.price } }
  }
}

These two files are the code you write. Everything under gen/, src/handler/ and docs/reference/ belongs to the build.

Check it worked

Run npm run build, then boot your own copy with npm run local. It prints MY-APP-BACKEND STARTED and keeps running, with a REPL on port 50502, the repl port in model/conf.aon. Open the REPL from a second terminal.

npx seneca-repl telnet://localhost:50502

Type aim:shop,get:product,id:p1 at its prompt. The store starts empty, so the reply is { ok: false, why: 'not-found' }. The sample’s script makes the same round trip on a scratch copy: it boots it the way src/env/local/local.ts does, saves two products, sends the message, then builds and boots again.

node send.mjs
npm run build, then boot
  files the build changed in the committed project: 0
  save shop/product {"id$":"p1","title":"Lamp","price":30}
    -> {"saved":"p1"}
  save shop/product {"id$":"p2","title":"Rug","price":"thirty"}
    -> {"error":"shape","message":"Entity: shop/product: Validation failed for property \"price\" with string \"thirty\" because the string is not of type number."}
  post {"aim":"shop","get":"product","id":"p1"}
    -> {"reply":{"ok":true,"product":{"id":"p1","title":"Lamp","price":30}}}
  post {"aim":"shop","get":"product","id":"p2"}
    -> {"reply":{"ok":false,"why":"not-found"}}
npm run build again, then boot
  files the second build changed: 0
  replies identical: true

The reply to aim:shop,get:product carries "title":"Lamp". The price:Number field from step three is enforced at runtime: the save with a string price is refused. The boot runner turns off the REPL, because npm run local keeps running until stopped. It printed MY-APP-BACKEND STARTED { version: '0.0.1' } in the recording.

The test asserts every line of that output, the hand-edit results in the next sections, and each step’s record.

node --test system.test.mjs
1..8
# tests 8
# suites 0
# pass 8
# fail 0
# cancelled 0
# skipped 0
# todo 0
# duration_ms 7783.447136

Add the same operation with OpenAPI Generator and NSwag

A team that generates its services with OpenAPI Generator or NSwag declares the same service as an OpenAPI document, others/shop-v1.json. Version two adds one operation, listProducts, the way step four added a message. Each generator then writes the declaration, and your code implements it in a file the generator never touches.

node others.mjs
OpenAPI Generator 7.27.0, typescript-nestjs-server
  files v2 changed: 2
  ShopApi v1: getProduct
  ShopApi v2: getProduct, listProducts
  tsc on shop-impl.ts: v1 exit 0, v2 exit 1
    shop-impl.ts(8,14): error TS2515: Non-abstract class 'ShopImpl' does not implement inherited abstract member listProducts from class 'ShopApi'.
  HAND EDIT lines in controllers/ShopApi.controller.ts: before 1, after regenerating 0
  with the controller in .openapi-generator-ignore: HAND EDIT lines after regenerating 1, listProducts in the controller 0, in ShopApi 1
NSwag version: 14.8.0.0, openapi2cscontroller
  IShopController v1: GetProductAsync
  IShopController v2: GetProductAsync, ListProductsAsync

OpenAPI Generator’s typescript-nestjs-server, which its page marks beta, writes an abstract ShopApi class and a controller that calls it. Your implementation extends the class, and TypeScript refuses a subclass that leaves an abstract member unwritten, so the added operation is a type error until you write it. The scaffold reports the same gap at boot or at the call instead. An edit inside the generated controller is lost on regeneration. Listing the file in .openapi-generator-ignore keeps the edit, but the controller then never receives the route for listProducts.

NSwag’s openapi2cscontroller writes one C# file holding an IShopController interface and a partial ASP.NET Core controller that forwards each route to it. Its ControllerStyle option takes partial or abstract, as nswag help openapi2cscontroller prints. A class that implements the v2 interface without ListProductsAsync is the C# compiler’s CS0535. The C# was not compiled here, because the sandbox has the .NET runtime and no SDK.

When it goes wrong

A hand edit in a generated file disappears at the next build. The build rewrites gen/, src/handler/ and the service README from the model, and keeps nothing it did not write. Put the change in the model, or in the action file, which the build compiles and never rewrites.

node pitfall.mjs
hand edits, then npm run build
  lost  backend/src/handler/lambda/shop.ts (generated)
  lost  backend/gen/env/aws/srv.yml (generated)
  lost  backend/src/srv/shop/README.md (generated)
  kept  backend/src/srv/shop/get_product.ts (yours)
  reply: {"reply":{"ok":true,"product":{"id":"p1","title":"Lamp","price":30,"currency":"EUR"}}}
a message in model/msg.aon with no action file: aim: shop: list: product: {}
  npm run build: ok
  reload on (npm run local): ready, then aim:shop,list:product -> {"error":"MODULE_NOT_FOUND","message":"Cannot find module './list_product'"}
  reload off: FATAL The definition action for the plugin srv_shop has failed: Cannot find module './list_product'

A message declared before its action file builds cleanly and then fails. The system’s explanation of model wiring says “A message without an action file fails loudly at boot”. That holds only with reload off, when the boot logs FATAL and never reaches ready. Under npm run local the system starts and the call fails with MODULE_NOT_FOUND, because @seneca/reload watches for the missing file instead of refusing it.2 Write the action file in the same change as the message.

The documented npm create fails with shape_1.One is not a function. A fresh install resolves shape 12, which lacks that export. Hold it at 11.4.1 through overrides, in the tool folder and in the backend, as the scaffold steps show.

Moving the backend to @voxgig/model 12.0.2 fails at once with source not found: @voxgig/model/model/sys.aon, because the scaffold’s model includes a file that release no longer ships. Keep every release the scaffold pins: the newest @voxgig/build and @voxgig/system fail the same way as the pinned ones.

When not to do this

Do not use @voxgig/system for a few HTTP endpoints that one team owns. A NestJS schematic or an Nx generator writes the files once, and then every line is yours to change, with no model to keep correct. The model earns its upkeep when several services, their messages, their entities and their deploy files must agree.

Do not adopt the scaffold without pinning it. On the day this page ran, the documented command, the first build and every add command each needed a workaround, and the newest releases of @voxgig/build and @voxgig/system failed the same way.

Pick OpenAPI Generator when the contract is HTTP and the team writes NestJS. Its abstract class puts a missing operation in front of the compiler, which a message model cannot do. Pick NSwag for the same reason in ASP.NET Core, where its interface turns an added route into a build error.

Do not edit generated files under any of the three. The scaffold and OpenAPI Generator each discarded a hand edit on regeneration here, and OpenAPI Generator’s ignore file saved an edit only by freezing the file it protected.

Last verified

Verified 2026-11-22 against Node 22.23.5, @voxgig/create-system 0.10.3, @voxgig/system 1.15.0, @voxgig/model 11.0.0, @voxgig/build 4.16.0, shape 11.4.1, Seneca 4.0.0-rc5 and TypeScript 7.0.2, the releases the scaffold installs with shape held by the two overrides. The same defects held on @voxgig/build 4.16.3 and @voxgig/system 1.15.1, the newest on npm, and @voxgig/model 12.0.2 failed to build the scaffold’s model, as records/08-*.txt shows. OpenAPI Generator 7.27.0 and NSwag 14.8.0 ran once, in record-generators.sh, and their output is committed. NestJS CLI schematics and Nx generators were read from their documentation and not run.

Footnotes

  1. The scaffold names its model files .aon, the CLI looks only for .aontu and .jsonic, and the build script runs voxgig-model model/model.aon. A symlink is the smallest object that satisfies all three. The extension list sits in lib/add.ts at line 44, in a release whose own reference page names the files srv.aontu and msg.aontu. ↩︎ Back to text

  2. The default that decides which of the two failures you meet is active: true in @seneca/reload, with the comment NOTE: set to false for production! beside it. Earlier in the same file, a missing action file is watched for creation under the note “calls to the action will still fail”. The scaffold’s local runner leaves the default alone and its Lambda runner turns it off, so development gets the forgiving failure and a deployed function the loud one. ↩︎ Back to text

Read this page as markdown · All how-to guides

Generate the client instead of writing it#

Retries, timeouts, pagination and auth are the same problems in every client. Voxgig generates them from your OpenAPI description, in 23 languages, from one model.

Listen to Fireside, the Voxgig podcast

Since 2018, Richard Rodger has talked with developer advocates, event organizers, and the people who build developer-facing companies about the specifics of the work.