docs: rank the destructive generator as item 0

It was written up in 4.7 but never made the work order, which is exactly how it stayed dangerous in the first place. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-08-09 11:18:45 +05:30
parent 790b81330a
commit 247f360ae7
79 changed files with 2759 additions and 146 deletions
@@ -1,19 +1,56 @@
-# Inter-app + external API showcase
+# Inter-app API showcase

-`GET /api/product-summary?sku=starter` demonstrates one request handler making:
+Generated with `wrnexus workspace inter-app-api-showcase`.

-1. an RPC request to the `catalog` app (`getProduct`);
-2. an external HTTPS request to GitHub's public REST API; and
-3. an RPC request to the `audit` app (`recordLookup`).
+- `web` exposes `GET /api/product` and calls admin through private RPC.
+- `admin` provides the `catalog` service.
+- `packages/shared` owns the typed contract imported by both apps.

-The handler deliberately forwards `as: ctx` only to WRNexus peer apps. The RPC package turns that into a short-lived subject/tenant token; it is never forwarded to GitHub. Each peer app must implement the same contract from `app/lib/contracts.ts` (normally a shared workspace package) under `app/services/`, and must authorize its own procedures.
+Run the verification from the repository root:

-Before running this app, configure all three apps with the same private internal-origin map and a distinct, 32+ character RPC secret:
-
-```sh
-WRNEXUS_RPC_SECRET=replace-with-a-private-32-character-minimum-secret
-WRNEXUS_APP_NAME=product-summary
-WRNEXUS_INTERNAL_ORIGINS={"catalog":"http://127.0.0.1:4101","audit":"http://127.0.0.1:4102"}
+```bash
+bun test examples/inter-app-api-showcase/apps/web/test/inter-app.test.ts
 ```

-The peer app processes must remain private; the public gateway blocks the RPC route by design. Run with `bun run --cwd examples/inter-app-api-showcase dev`.
+A WrNexus **workspace** — multiple apps, one gateway, interconnected.
+
+```
+inter-app-api-showcase/
+  wrnexus.workspace.ts   # apps ↔ domains map (used by `wrnexus gateway`)
+  apps/
+    web/                # a WrNexus app  → localhost, web.localhost
+    admin/              # a WrNexus app  → admin.localhost
+  packages/
+    shared/             # @app/shared — shared code + cross-app pubsub bus
+```
+
+## Run everything (one port, routed by domain)
+
+```bash
+bun install
+bun run dev            # = wrnexus gateway  → http://127.0.0.1:3000
+```
+
+Add the hosts to your machine (e.g. /etc/hosts):
+
+```
+127.0.0.1 web.localhost admin.localhost
+```
+
+Open `http://localhost:3000` for the web app or
+`http://admin.localhost:3000` for the admin app. The ports printed for individual
+apps are internal gateway targets, not public workspace URLs.
+
+## Interconnect
+
+- **Shared code:** import `@app/shared` in any app.
+- **Runtime messaging:** `import { bus } from "@app/shared"` then
+  `bus.publish("tenant:created", {...})` in one app and
+  `bus.subscribe("tenant:*", fn)` in another (needs Redis).
+- **Databases:** point apps at the same `db`/`databases` in their config.
+
+## Add another app
+
+```bash
+wrnexus workspace add reports --domain=reports.localhost
+```