SYSTEM VIEW

Which service calls which, pinned to both ends

One links.json records every call between your services: the client that makes it and the handler that serves it, each held by a content hash. It draws as one map, and vibex links --check fails CI when either end moves.

Open the example Install the skill

> how do these services talk to each other?

wrote system.links.json · 5 calls across 3 services

# pin every call, then check it in CI

$ vibex links system.links.json docs --repo bff=../bff \

--repo orders=../orders --check

One map across repositories

The example ships with vibeX: a BFF, an order API and Stripe, in two repositories. Each arrow is one service pair, labelled with how many calls sit behind it.

shop.links.html · 3 services · 5 calls · 2 repositoriesFull screen ↗

Click an arrow for every route behind it. In a dashboard, the System view is the first panel.

What one call holds

{
  "id": "bff-list-orders",
  "from": "bff",
  "to": "order_api",
  "kind": "http",
  "route": "GET /orders",
  "env": "ORDER_API_URL",
  "endpoint": "shop.endpoints#list-orders",
  "client": {
    "path": "src/orders/orders.client.ts",
    "symbol": "listOrders",
    "hash": "96b21191949e"
  },
  "handler": {
    "path": "src/orders/orders.controller.ts",
    "symbol": "listOrders",
    "hash": "7d2f6abf5244"
  }
}

A link is found on both ends or not written at all. The skill finds the HTTP or GraphQL client in one service, then the controller or resolver that serves the route in the other.

client and handler are anchors: a file, a symbol and a hash of its lines. Change either method and the link flags itself.

A third party such as Stripe is a service with "external": true. Its side needs no anchor.

SERVICES

repo: The name given to --repo name=dir. Leave it out in a monorepo.
spec · ignore: The service's endpoints spec, so the check can list routes nothing calls. ignore hides health and docs routes.
c4: The C4 elements this service is drawn as, so the check can compare the diagram with the calls.

What the check reports

$ vibex links shop.links.json . --repo bff=bff --repo order-api=order-api --check

5 links — 4 ok, 1 broken, 6 endpoint(s) nothing calls

changed bff-list-orders (bff → order_api GET /orders) client: src/orders/orders.client.ts changed since this call was last confirmed

uncalled order_api GET /orders/{id} (shop.endpoints#get-order)

shop.c4: matches the links

Fails --check

Exit 1. Each line names the call and the file.

changedthe client or handler lines changed since the call was confirmed
missingthe file or the symbol is gone
danglingthe endpoint it points at is not in the endpoints spec
no-repoa service whose repository was not passed with --repo, so its end cannot be read
C4 driftan arrow with no call behind it, a call with no arrow, or a neighbour the diagram leaves out

Reported

Printed, never blocking.

uncalledan endpoint no service calls. Dead, or called from outside what you mapped

It records calls, it does not trace them. The map shows what the code can call, read from clients and handlers. It does not watch traffic, so a call built at runtime from a string it cannot follow is reported as a finding, not guessed.

Many repositories or one

Give each repository a name and the check reads every anchor from the right one. In a monorepo, pass the root once and use root-relative paths.

# one directory per service

$ vibex links system.links.json docs --repo bff=../bff --repo orders=../orders

# a monorepo

$ vibex links system.links.json docs --repo .

# after you have re-read a moved call

$ vibex links system.links.json docs --repo . --reanchor

What it connects to

Arrows the code backs

Map each service to its C4 elements and the check tells you when the diagram and the calls disagree. Fix the C4, not the links.

C4 →

ENDPOINTS

Routes nothing calls

With the endpoints spec attached, every route no service calls is listed.

Endpoints →

DASHBOARD

First panel in the file

A links spec in the folder becomes the System panel, ahead of every other diagram.

Dashboard →