# 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.

Source: https://voxgig.com/howto/scaffold-a-service-system-from-a-model

- Audience: platform-team
- Level: beginner
- Languages: typescript
- Verified: 2026-11-22
- Published: 2026-11-22

## 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](https://senecajs.org/) 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

| Approach | When it fits | What it costs you | When to pick something else |
| --- | --- | --- | --- |
| [@voxgig/system with create-system](https://github.com/voxgig/system) | Message services in Seneca, declared in one model that also generates deploy files and docs | Two shape overrides and a symlink before it builds, and a model you keep correct | Your services speak HTTP to each other and the team writes NestJS |
| [NestJS CLI schematics](https://docs.nestjs.com/cli/usages) | A NestJS app where each controller or resource is written once and then owned | Each run writes files from its options and keeps no model, so the code drifts from any description | Several services must stay in step with one contract |
| [NSwag](https://github.com/RicoSuter/NSwag/wiki/CSharpControllerGenerator) | ASP.NET Core services generated from an OpenAPI document | You run it under .NET, and the compiler, not a boot, reports a missing method | Your services are not .NET |
| [Nx generators](https://nx.dev/docs/features/generate-code) | A monorepo that wants house conventions in every scaffold | You write and maintain each generator, and a one-shot generator's output is yours once it runs | The files must follow a model you edit, unless you write a sync generator for it |
| [OpenAPI Generator](https://openapi-generator.tech/docs/generators/typescript-nestjs-server/) | A NestJS server whose routes come from an OpenAPI document | A beta generator, and a protected controller stops receiving the routes you add | Your 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](https://nx.dev/docs/concepts/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](https://docs.npmjs.com/cli/v10/configuring-npm/package-json/#overrides).

```bash
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.

```bash
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.

```bash
ln -s model.aon model/model.aontu
```

The CLI's extension list is `['aontu', 'jsonic']`,[^1] and create-system's own
[tutorial](https://github.com/voxgig/create-system/blob/main/docs/tutorial.md) 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.

```bash
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.

```bash
node steps.mjs
```

```text output
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.

```bash
node steps.mjs msg
```

```text output
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`](https://github.com/voxgig/system/blob/v1.15.0/system.ts).

```ts title="my-app/backend/src/srv/shop/shop-srv.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.

```ts title="my-app/backend/src/srv/shop/get_product.ts"
// 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.

```bash
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.

```bash
node send.mjs
```

```text output
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.

```bash
node --test system.test.mjs
```

```text output
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.

```bash
node others.mjs
```

```text output
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](https://www.typescriptlang.org/docs/handbook/2/classes.html) 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`](https://openapi-generator.tech/docs/customization/) 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](https://learn.microsoft.com/en-us/aspnet/core/web-api/?view=aspnetcore-11.0)
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](https://learn.microsoft.com/en-us/dotnet/csharp/language-reference/compiler-messages/interface-implementation-errors).
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.

```bash
node pitfall.mjs
```

```text output
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](https://github.com/voxgig/system/blob/main/docs/explanation/model-wiring.md)
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.

## Related how-tos

- [Add user accounts to a message-based service](/howto/add-user-accounts-to-a-message-service)

- [Contract test messages between services](/howto/contract-test-messages-between-services)

- [Find hand edits in a generated SDK before you regenerate](/howto/find-hand-edits-before-regenerating)

- [Emit TypeScript types and SQL from one application model](/howto/generate-typescript-types-and-sql-from-one-model)

- [Split an application model into entity and service files](/howto/split-an-application-model-into-aon-files)

## 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.

[^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`](https://github.com/voxgig/system/blob/v1.15.0/lib/add.ts)
at line 44, in a release whose own reference page names the files `srv.aontu` and `msg.aontu`.

[^2]: The default that decides which of the two failures you meet is `active: true` in
[`@seneca/reload`](https://github.com/senecajs/seneca-reload/blob/v0.5.0/src/reload.ts), 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.