# How to split a monolith along API resource boundaries

> Read the first service seams off an OpenAPI document, then check each against the import graph and the tables each query touches, and cut where all three agree.

Source: https://voxgig.com/howto/split-a-monolith-along-api-resource-boundaries

- Audience: api-producer
- Level: advanced
- Languages: typescript
- Verified: 2026-11-22
- Published: 2026-11-22

## Short answer

Extract the resources from the OpenAPI document with @voxgig/apidef and read the import graph of the handler modules with dependency-cruiser. List every query that touches tables of more than one resource through SQLite's EXPLAIN. Lay all three over the bounded contexts from event storming, and cut a context only where the spec, the code, and the data agree. In the sample shop, only Publishing passes.

---
## You will need

Node 22.13 or later, the monolith's OpenAPI 3 document, its handler modules, and its database
schema. The sample is a shop with 16 operations, six handler modules, and seven tables in
`monolith/shop.db`. It reads the file with
[`node:sqlite`](https://nodejs.org/docs/latest-v22.x/api/sqlite.html), which needs no flag from
Node 22.13 and prints an experimental warning on stderr. Run `npm ci` in the sample directory
first.

## Approaches compared

| Approach | When it fits | What it costs you | When to pick something else |
| --- | --- | --- | --- |
| [apidef entity extraction](https://github.com/voxgig/apidef/blob/main/docs/explanation/classification-heuristics.md) | You want resources named from paths and schemas, with parent keys, in a file you can diff | A heuristic per release: the same document can classify differently on the next version | Your tags were designed as service names and are kept that way |
| [dependency-cruiser import graph](https://github.com/sverweij/dependency-cruiser/blob/main/doc/api.md) | The handlers live in modules whose imports are static and resolvable | Sees imports only, so two modules sharing a table look independent | Coupling runs through the database rather than through code |
| [Event storming into bounded contexts](https://www.eventstorming.com/) | Several teams own the domain and the seam must match who owns what | A workshop with domain experts, and an outcome no tool can check against the code | Nobody who knows the business is available for a day |
| [Kiota request builders](https://learn.microsoft.com/en-us/openapi/kiota/using) | You generate clients with Kiota and want one client per seam from one document | Follows the path tree, so a nested resource keeps its parent's builders in every call | Your seams cut across path prefixes |
| [OpenAPI tags and paths read by hand](https://spec.openapis.org/oas/v3.0.3#tag-object) | A small document whose tags were written with care | Tags drift from paths, and nobody sees a disagreement until a cut breaks | The document has more operations than a reviewer holds in mind |
| [Swagger Codegen tag classes](https://swagger.io/docs/open-source-tools/swagger-codegen/codegen-v3/generation-selective/) | You generate clients with Swagger Codegen and your tags are the intended service names | One API class per tag, so a stray tag becomes a class of its own | Your tags group by audience or by team rather than by resource |

Voxgig maintains apidef, the extractor behind sdkgen. It is one of six readings on this page.
Voxgig makes no other tool or method in the table.

No single row finds a seam. The spec readings are stable and visible to clients, but they cannot
see a join. The import graph sees code and misses the database. Event storming matches the
seams to the teams,[^1] and leaves you to prove that the code agrees.

## Read the document three ways

`resources.mjs` reads every operation by its first tag, by its first path segment, and by the
entity `@voxgig/apidef` 8.32.4 puts it on. That is the release
[`@voxgig/create-sdkgen`](https://github.com/voxgig/create-sdkgen) 0.31.9 installs, pinned here in
the lockfile.

```bash
node resources.mjs
```

```text output
operation                                       tag       prefix    apidef 8.32.4
GET    /orders                                  Orders    orders    order.list
POST   /orders                                  Orders    orders    order.create
GET    /orders/{orderId}                        Orders    orders    order.load
GET    /products                                Catalog   products  product.list
GET    /products/{productId}                    Catalog   products  product.load
DELETE /user/{id}                               Admin     user      user.remove
GET    /user/{id}                               Accounts  user      user.load
GET    /users                                   Users     users     user.list
POST   /users                                   Users     users     user.create
GET    /users/{userId}                          Users     users     user.load
PUT    /users/{userId}                          Users     users     user.update
GET    /users/{userId}/posts                    Posts     users     post.list
POST   /users/{userId}/posts                    Posts     users     post.create
GET    /users/{userId}/posts/{postId}           Posts     users     post.load
GET    /users/{userId}/posts/{postId}/comments  Comments  users     comment.list
POST   /users/{userId}/posts/{postId}/comments  Comments  users     comment.create

groups: 7 tags, 4 prefixes, 5 entities
  comment  parent keys: post_id, user_id
  order    parent keys: none
  post     parent keys: user_id
  product  parent keys: none
  user     parent keys: none
warning: Points GET /user/{id} and GET /users/{userId} on entity=user op=load have the same selector (exist: id), so only GET /user/{id} is ever chosen. An action or another entity in guide.aontu tells them apart.
```

Three readings, three answers: seven tag groups, four path prefixes, five entities. The legacy
`/user/{id}` paths carry the tags `Accounts` and `Admin`, so a tag reading invents two resources.
On this document both apidef releases put those operations on `user`.

The parent keys matter for the cut. Every post and comment URL carries `user_id`, so the clients
of a Publishing service still address it through `/users/{userId}`. That is a routing rule at the
gateway, not a join.

The warning matters more than the counts. On 8.32.4 a plain `load` reaches only the legacy
`GET /user/{id}`, so the canonical `GET /users/{userId}` is never chosen.
`legacy-load-guide.aontu` gives the legacy path an action of its own, and the test shows 8.32.4
then choosing `/users/{userId}` for a plain load, with no warning.

`generate.sh` records the same command on apidef 8.33.1, the newest release, in
`generated/apidef-8.33.1.txt`. It finds the same five entities, prints no warning, and marks the
two `/users/{userId}` points with `$action=users`, so 8.33.1 hides the canonical path behind an
action instead. With the guide file, 8.33.1 keeps that action, so check the release you pin.

## Measure the coupling between handlers

`coupling.mjs` asks dependency-cruiser for the import graph of `monolith/handlers` and keeps the
edges between handler modules.

```bash
node coupling.mjs
```

```text output
imports between handler modules
  accounts -> users
  comments -> posts
  orders -> products
  orders -> users
```

Orders imports a display-name helper from users and a price formatter from products. Accounts and
comments import from modules in their own context, which costs nothing at the cut.

## List the queries that cross resources

An import graph cannot see two modules that share a table. SQLite can: every table a statement
opens appears in its `EXPLAIN` program as an `OpenRead` or `OpenWrite` step whose second operand
is the table's [root page](https://www.sqlite.org/opcode.html).[^2] `joins.mjs` runs `EXPLAIN` on
each handler query against `monolith/shop.db`, once with foreign keys off and once with them on,
and records which tables come from the statement and which from a key check.

```ts title="joins.mjs"
export function tablesTouched(dbFile, sql) {
  const plain = new DatabaseSync(dbFile, { readOnly: true, enableForeignKeyConstraints: false })
  const checked = new DatabaseSync(dbFile, { readOnly: true, enableForeignKeyConstraints: true })
  try {
    const own = opened(plain, sql)
    const all = opened(checked, sql)
    return [...all].sort().map((tbl) => ({ tbl, via: own.has(tbl) ? 'statement' : 'foreign key' }))
  } finally {
    plain.close()
    checked.close()
  }
}
```

It loads those rows and the owner of each table from `contexts.json` into two temporary tables,
then runs one query.

```sql title="cross-resource-joins.sql"
SELECT q.module,
       q.query,
       count(DISTINCT q.tbl) AS tables,
       count(DISTINCT CASE WHEN q.via = 'foreign key' THEN q.tbl END) AS through_keys,
       replace(group_concat(DISTINCT o.resource ORDER BY o.resource), ',', ', ') AS resources
FROM query_table q
JOIN table_owner o ON o.tbl = q.tbl
GROUP BY q.module, q.query
HAVING count(DISTINCT o.resource) > 1
ORDER BY tables DESC, q.module, q.query;
```

```bash
node joins.mjs
```

```text output
queries that touch more than one resource
  orders.loadOrder         5 tables: order, product, user
  accounts.deleteUser      3 tables, 2 through a foreign key: order, user
  orders.addItem           3 tables, 2 through a foreign key: order, product
  orders.createOrder       3 tables, 2 through a foreign key: order, user
  comments.createComment   2 tables, 1 through a foreign key: comment, post
```

`orders.loadOrder` is the pitfall: one statement over orders, order lines, products, users and
addresses. The other four rows cross resources only through foreign keys. Deleting a user opens
`orders` because a [foreign key](https://www.sqlite.org/foreignkeys.html) on `orders.user_id`
points at it, so a split that puts orders in another database has to replace that check.[^3]

A reference without a key is invisible here. `posts.user_id` and `comments.user_id` hold user ids
with no `REFERENCES` clause, so no statement opens `users`. A test declares the key on
`posts.user_id`, and `posts.createPost` then opens `users` and Publishing waits.

## Cut only where the readings agree

`contexts.json` holds what the event-storming session decided: four contexts, the modules and
resources in each, and the resource that owns each table.

```json title="contexts.json"
{
  "contexts": {
    "Catalog": { "modules": ["products"], "resources": ["product"] },
    "Identity": { "modules": ["accounts", "users"], "resources": ["user"] },
    "Publishing": { "modules": ["comments", "posts"], "resources": ["comment", "post"] },
    "Sales": { "modules": ["orders"], "resources": ["order"] }
  },
  "tables": {
```

`seams.mjs` checks each context against all three readings. Spec: its modules serve every
operation on its entities and no other. Code: no import crosses its boundary, in either direction.
Data: no query touches its tables together with another context's.

```bash
node seams.mjs
```

```text output
Catalog: wait
  spec  every operation served inside
  code  orders -> products
  data  orders.loadOrder, orders.addItem
Identity: wait
  spec  every operation served inside
  code  orders -> users
  data  orders.loadOrder, accounts.deleteUser, orders.createOrder
Publishing: cut
  spec  every operation served inside, refers to user_id (Identity)
  code  none
  data  none
Sales: wait
  spec  every operation served inside
  code  orders -> products, orders -> users
  data  orders.loadOrder, accounts.deleteUser, orders.addItem, orders.createOrder
```

Publishing is the cut. Its only reference out is the `user_id` key in its paths, a value rather
than a join. Catalog and Identity look independent in the spec and wait on Sales, whose load query
reads their tables and imports their modules. Until orders stops doing both, neither can move
without it.

## Carve the same seam in Kiota and Swagger Codegen

A team that generates its SDK with Kiota or Swagger Codegen meets the seam again in the client.
`generate.sh` ran each of them twice on `monolith/openapi.json`. The first run covered the whole
document and the second the Publishing paths alone, and the script committed a summary of each tree.

```bash
node generators.mjs
```

```text output
Kiota 1.39.0, whole document: 16 operations
  top-level builders: orders, products, user, users
Kiota, --include-path /users/{userId}/posts --include-path /users/{userId}/posts/**
  users/item/posts/index.ts                GET POST
  users/item/posts/item/comments/index.ts  GET POST
  users/item/posts/item/index.ts           GET
  navigation only: users/index.ts, users/item/index.ts
Kiota, --include-path /users/{userId}/posts/** alone
  users/item/posts/item/comments/index.ts  GET POST
  users/item/posts/item/index.ts           GET
Swagger Codegen 3.0.85, whole document: 16 operations
  API classes: AccountsApi, AdminApi, CatalogApi, CommentsApi, OrdersApi, PostsApi, UsersApi
Swagger Codegen, -Dapis=Posts,Comments
  CommentsApi  createComment listComments
  PostsApi     createPost listPosts loadPost
  models: Comment, CommentInput, Post, PostInput
```

Kiota builds its request builders from path segments, as its
[request builders page](https://learn.microsoft.com/en-us/openapi/kiota/request-builders)
describes, so its four top-level builders match the four prefixes. `--include-path` gives a
Publishing client from the same document. The glob `/users/{userId}/posts/**` alone left out the
collection itself, the list and create on `posts`, so the seam run passes the bare path too. The
`users` builders stay, without operations, because the call chain starts there.

On this document, Swagger Codegen 3.0.85 wrote one API class per tag, seven in all, `AccountsApi`
and `AdminApi` among them. [Selective generation](https://swagger.io/docs/open-source-tools/swagger-codegen/codegen-v3/generation-selective/)
with `-Dapis=Posts,Comments`, a `-Dmodels` list, and `-DsupportingFiles` gives the seam's client.
The `typescript-fetch` target keeps its API classes in `api.ts`, and without `-DsupportingFiles`
the run wrote no file and exited 0. Neither tool reads the code or the tables, so neither
replaces the overlay. Swagger
Codegen shows the tag reading in the class list a client team works with, and Kiota's
`kiota-lock.json` keeps the include patterns beside the generated client.

## Check it worked

The test fails if the overlay passes a context it should not. It feeds the overlay one extra
import and one extra join, and the Publishing verdict must turn to `wait`. It also refuses an
entity or a module no context claims, and a table no resource owns.

```ts title="seams.test.mjs"
test('one new import or one new join turns the Publishing cut into a wait', () => {
  const a = inputs()
  a.edges.push({ from: 'comments', to: 'users' })
  assert.equal(verdicts(overlay(a)).Publishing, 'wait')
  const b = inputs()
  b.joins.push({ module: 'comments', query: 'listComments', tables: 2, resources: 'comment, user' })
  assert.equal(verdicts(overlay(b)).Publishing, 'wait')
})
```

```bash
node --test seams.test.mjs
```

```text output
1..16
# tests 16
# suites 0
# pass 16
# fail 0
# cancelled 0
# skipped 0
# todo 0
# duration_ms 690.548356
```

## When it goes wrong

The join list is empty for a query you know joins. It is built at run time, so it never reached a
handler's `queries`. The finder reads only what each module declares, so move the SQL there.

A context passes that should not. The owner map in `contexts.json` names the wrong resource for a
table, so the join looks internal. The finder refuses a table with no owner, and a wrong owner
needs review.

The spec reading changes after an upgrade. apidef classifies by heuristics that move between
releases, as the `$action=users` difference between 8.32.4 and 8.33.1 shows. Pin the version in
the lockfile, and run the newest one in a recording step before you move to it.

## When not to do this

Do not cut along resources because the spec says so. A path prefix is a promise to clients, not a
statement about the data, and the order query here crosses three resources under one prefix.

Do not adopt apidef only to read your seams. If your client generator is Kiota, its path tree
already gives the prefix reading, and `--include-path` gives a client per seam. If you use Swagger
Codegen and your tags are service names, its class list is the tag reading with nothing else to
install.

Do not trust an empty join list from a monolith whose SQL comes from an ORM. The queries exist
only at run time, so record them from the test suite instead of from module exports.

Skip the overlay for a monolith with one team and three modules. The workshop and the scripts
cost more than reading three folders.

## Related how-tos

- [Split a monolith into message-based services with Seneca](/howto/split-a-monolith-into-message-based-services)

- [Reconcile an extracted entity model with a domain model](/howto/reconcile-an-extracted-model-with-a-domain-model)

- [Diff two semantic models from successive spec versions](/howto/diff-two-semantic-models-across-versions)

## Last verified

Verified 2026-11-22 against Node 22.23.5, @voxgig/apidef 8.32.4, dependency-cruiser 18.8.0, Kiota
1.39.0 and Swagger Codegen 3.0.85. Kiota and Swagger Codegen ran once, in `generate.sh`, and the
page reads the summaries it committed. The two apidef 8.33.1 runs are from that script too. The
apidef range a scaffold installs was read from the `package.json` template in @voxgig/create-sdkgen
0.31.9.

[^1]: Melvin Conway's [paper on how committees invent](https://www.melconway.com/Home/Committees_Paper.html)
appeared in Datamation in April 1968. Its thesis, that organizations which design systems produce
copies of their own communication structures, sits in the third-last paragraph. The author's note
on the reprint, written 42 years after publication, says this is perhaps the paper's most
remarkable feature.

[^2]: SQLite's [own page on EXPLAIN](https://www.sqlite.org/lang_explain.html) says its output is
intended for interactive analysis and troubleshooting only. The format may change from one release
to the next, the page adds, and programs should not use it. The join finder uses it anyway, and
its test pins the five tables the order query must open.

[^3]: SQLite ships with [foreign key constraints off](https://www.sqlite.org/foreignkeys.html), for
backwards compatibility, and each connection turns them on for itself. Node 22's `DatabaseSync`
[turns them on](https://nodejs.org/docs/latest-v22.x/api/sqlite.html) unless `enableForeignKeyConstraints` is false,
so the same file answers `EXPLAIN` differently depending on who opened it, which is the
difference `joins.mjs` measures.