# systemlynx

Latest version **3.6.2** (published 2026-10-27) · ISC license · 0 weekly downloads

## Install

```sh
npm install systemlynx
pnpm add systemlynx
yarn add systemlynx
bun add systemlynx
```

## Health

**Score 55/100 (C)** — status: active.

Positive: no vulnerabilities; recently updated; high maintenance score.

Warnings: low downloads; no types; no esm support.

## Facts

| | |
|---|---|
| Version | 3.6.2 |
| Published | 2026-10-27 |
| First published | 2022-10-15 |
| Weekly downloads | 0 |
| License | ISC |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 7 |
| Unpacked size | 382.3 KB |
| Known vulnerabilities | 0 (+11 in 1 direct dependencies) |
| Install scripts | no |
| GitHub stars | 4 |
| Author | odion edwards |
| Maintainers | odion |

## Links

- npm: https://www.npmjs.com/package/systemlynx
- Repository: https://github.com/Odion100/SystemLynx
- Homepage: https://github.com/Odion100/SystemLynx#readme
- Issues: https://github.com/Odion100/SystemLynx/issues
- npm.io page: https://npm.io/package/systemlynx

## Dependencies (7)

- [mime](https://npm.io/package/mime.md) ^2.4.0
- [axios](https://npm.io/package/axios.md) ^1.5.0
- [multer](https://npm.io/package/multer.md) ^1.4.2
- [express](https://npm.io/package/express.md) ^4.18.2
- [shortid](https://npm.io/package/shortid.md) ^2.2.14
- [socket.io](https://npm.io/package/socket.io.md) ^4.8.1
- [socket.io-client](https://npm.io/package/socket.io-client.md) ^4.8.1

## Recent versions

- 3.6.2 (latest) — 2026-10-27
- 3.6.1 — 2026-09-12
- 3.6.0 — 2026-09-09
- 3.5.0 — 2026-08-29
- 3.4.0 — 2026-08-23
- 3.3.2 — 2026-08-08
- 3.3.1 — 2026-08-08
- 3.3.0 — 2026-08-07
- 3.2.1 — 2026-07-30
- 3.2.0 — 2026-07-26
- 3.0.0 — 2026-07-19
- 2.2.0 — 2026-07-10
- 2.1.0 — 2026-07-05
- 2.0.0 — 2026-07-01
- 1.21.0 — 2026-06-28
- … 32 more at https://npm.io/package/systemlynx/versions

## README

<img src="./logo.png" alt="Alt text" style="background:white; border-radius:20px; padding:10px"/>

# SystemLynx JS ![GitHub license](https://img.shields.io/badge/license-MIT-blue.svg) ![PRs Welcome](https://img.shields.io/badge/PRs-welcome-blue.svg) ![JS 100%](https://img.shields.io/badge/JavaScript-100%25-green)

SystemLynx is a Node.js framework for building modular, distributed web applications using an RPC-style architecture. It enables services to expose structured modules whose methods can be invoked remotely from client applications, abstracting away much of the complexity of client-to-service communication.

Built on top of Express and Socket.io, SystemLynx supports both request-response and real-time communication patterns, allowing developers to build scalable APIs and event-driven systems with a unified interface.


SystemLynx comes with the following objects that are used for web app development:

```javascript
const { App, Service, Client, LoadBalancer } = require("systemlynx");
```

- **Service** - Used to create and host objects that can be loaded and used by a SystemLynx Client.
- **Client** - Used in a client application to load a **Service**, providing access to all the objects hosted by the **Service**.
- **App** - provides a modular interface for creating and loading Services.

Find the full [API Documentation](https://github.com/Odion100/SystemLynx/blob/master/docs/API.md#tasksjs-api-documentation) here.

---

## ⚠️ Version compatibility

Starting with **v2.0.0**, SystemLynx delivers server-to-client WebSocket events using Socket.io **named events and rooms** — each client receives only the events it subscribed to, instead of a shared broadcast channel. This is a **wire-protocol change**, so a service and its clients must be on matching major versions:

| SystemLynx (service) | [`systemlynx-client`](https://www.npmjs.com/package/systemlynx-client) (browser / ESM) |
| :--- | :--- |
| `2.x` | `2.x` |

Pairing a v2 service with a v1 client (or vice versa) will connect successfully but **silently deliver no events**. Upgrade both sides together.

This coupling extends across the whole SystemLynx ecosystem: **[SystemView](https://www.npmjs.com/package/systemview)** and its SystemLynx plugin must also be on **v2.x** to work with v2 services and clients. Upgrade the entire stack together.

---

# Quick Start

## Service.module(name, constructor [,options])

Use the `Service.module(name, constructor/object)` method to add an object to be hosted by a **SystemLynx Service**. This will allows you to load an instance of that object into a client application, and call any methods on that object remotely.

```javascript
const { Service } = require("systemlynx");

const Users = {};

Users.add = function (data) {
  console.log(data);
  return { message: "You have successfully called the Users.add method" };
};

Service.module("Users", Users);
```

In the code above we assigned an object to the variable `Users` and gave it an add method. The `Service.module(name, constructor/object)` function takes the name assigned to the object as the first argument and the object itself as the second argument.

Alternatively, you can use a constructor function instead of an object as the second argument. In the example below we create another **Module** called "Orders". This time we use a constructor function as the second argument of the to **Service.module** function. The `this` value is the initial instance of the **Module** object. Every method added to the `this` value will be accessible when the object is loaded by a **SystemLynx Client**. Note: **Module** methods can be synchronous or asynchronous functions.

```javascript
const { Service } = require("systemlynx");

const Users = {};

Users.add = function (data) {
  console.log(data);
  return { message: "You have successfully called the Users.add method" };
};

Service.module("Users", Users);

Service.module("Orders", function () {
  const Orders = this;

  Orders.find = async function (arg1, arg2) {
    console.log(arg1, arg2);
    return { message: "You have successfully called the Orders.find method" };
  };
});
```

## Service.startService(options)

Before we can access the objects hosted by this **Service** from a client application, we need to call the `Service.startService(options)` function. This will start an **ExpressJS** Server and a **Socket.io** WebSocket Server, and set up routing for the **Service**. In the example below we added the `Service.startService(options)` function at the bottom, but the order does not matter.

```javascript
const { Service } = require("systemlynx");

const Users = {};

Users.add = function (data) {
  console.log(data);
  return { message: "You have successfully called the Users.add method" };
};

Service.module("Users", Users);

Service.module("Orders", function () {
  const Orders = this;

  Orders.find = async function (arg1, arg2) {
    console.log(arg1, arg2);
    return { message: "You have successfully called the Orders.find method" };
  };
});

Service.startService({ route: "test/service", port: "4400", host: "localhost" });
```

Now lets see how these objects can be loaded into a client application.

## Client.loadService(url, [options])

The `Client.loadService(url)` function can be used to load a SystemLynx **Service**. This method requires the url (string) of the **Service** you want to load as the first argument, and will return a promise that will resolve into an object that containing all the modules hosted by that service. See below. **NOTE: You must be within an async function in order to use the `await` keyword when returning a promise.**

```javascript
const { Client } = require("systemlynx");

const { Users, Orders } = await Client.loadService("http://localhost:4400/test/service");

console.log(Users, Orders);
```

Now that we've loaded the **Service** that we created in the previous example, and have a handle on the **Users** and **Orders** objects hosted by the **Service**, we can now call any method on those objects in the same way we would remotely. In the example below, noticed that both the `User.add` and `Orders.find` methods will return a promise.

```javascript
const { Client } = require("systemlynx");

const { Users, Orders } = await Client.loadService("http://localhost:4400/test/service");

console.log(Users, Orders);

const results = await Users.add({ message: "Users.add Test" });

console.log(results);

const response = await Orders.find("hello", "world");

console.log(response);
```

## Sending and Receiving Websocket Events

We can also receive WebSocket events emitted from the remote objects we've loaded using the `Client.loadService(url)` function. In the example below we're using the `Users.on(event_name, callback)` method to listen for events coming from the "Users" **Module**.

```javascript
const { Client } = require("systemlynx");

const { Users, Orders } = await Client.loadService("http://localhost:4400/test/service");

console.log(Users, Orders);

const results = await Users.add({ message: "Users.add Test" });

console.log(results);

Users.on("new_user", function (event) {
  console.log(event);
});

const response = await Orders.find("hello", "world");

console.log(response);
```

Now let's go to our server application and call the `Users.emit(event_name, data)` method to emit a websocket event that can be received by its corresponding Clients. Below, notice that we've added `this.emit("new_user", { message:"new_user event test" })` at the end of the `Users.add` method, so the `new_user` event will be emitted every time this method is called. The `this` value of a **Module** method will always be scoped to the **Module** itself.

```javascript
const { Service } = require("systemlynx");

const Users = {};

Users.add = function (data) {
  console.log(data);
  this.emit("new_user", { message: "new_user event test" });
  return { message: "You have successfully called the Users.add method" };
};

Service.module("Users", Users);

Service.module("Orders", function () {
  const Orders = this;

  Orders.find = async function (arg1, arg2) {
    console.log(arg1, arg2);
    return { message: "You have successfully called the Orders.find method" };
  };
});

Service.startService({ route: "test/service", port: "4400", host: "localhost" });
```

---

# Serving your modules to AI agents (MCP)

The same modules you already host can be served as [MCP](https://modelcontextprotocol.io) tools, so an agent can call them the same way your own code does — through the front door, with your middleware and auth intact.

```javascript
const { Service, createMCPServer } = require("systemlynx");

Service.module("Repo", Repo);
Service.module("Codebase", Codebase);

const mcp = createMCPServer(Service);

mcp.schema("Repo", {
  findRfc: {
    description:
      "Search every RFC in this repo for a word or phrase and return the ones that mention it. Use this first when you need to know whether a decision was written down.",
    input: { query: { type: "string", description: "a word or phrase, case-insensitive" } },
    required: ["query"],
  },
});

// One endpoint, exposing exactly what you chose. Serve as many as you like.
mcp.serve("repo-mcp", { expose: ["Repo.findRfc"] });

await Service.startService({ route: "workbench", port: 6400 });
```

Point an agent at it:

```
claude mcp add --transport http repo http://localhost:6400/workbench/repo-mcp
```

**A method becomes a tool only when it has a schema *and* a route exposes it.** Nothing is published because it happens to exist, so `signUp`, `deleteAll` and `patchLocations` are never reachable because someone forgot.

Two things worth knowing up front:

- **The `description` is the entire interface a model decides from.** Say what it does *and* when to reach for it.
- **A method meant to be consumed should take one object.** MCP hands a tool one object, so `({ id })` fits and `(pattern, dir)` does not — the server refuses the latter rather than letting it return a confident empty answer.

You can also front a service you don't own, without modifying it:

```javascript
const mcp = createMCPServer("http://localhost:4400/api");   // a URL, not a Service
await mcp.start({ port: 6400, route: "mcp" });
```

And consume any MCP server — SystemLynx or not — from either client:

```javascript
const tools = await Client.loadMCP("http://localhost:6400/mcp/repo-mcp");
await tools.Repo.findRfc({ query: "teardown" });
```

See the [API Documentation](https://github.com/Odion100/SystemLynx/blob/master/docs/API.md#mcpserver) for the full MCP API.

---

# Middleware

SystemLynx supports middleware that runs before or after a module method is called. This is useful for things like authentication, logging, or validating requests.

Use `Service.before` to add a middleware function that runs before any method is invoked, and `Service.after` to run one after the response is ready.

```javascript
const { Service } = require("systemlynx");

Service.before(function (req, res, next) {
  console.log("Incoming request:", req.fn);
  next();
});

Service.module("Users", Users);
Service.module("Orders", Orders);

Service.startService({ route: "api", port: 4400, host: "localhost" });
```

You can also scope middleware to a specific module or method so it only runs where you need it.

```javascript
// Runs before every method on the Users module
Service.before("Users", authMiddleware);

// Runs only before Users.delete
Service.before("Users.delete", requireAdminMiddleware);
```

See the [API Documentation](https://github.com/Odion100/SystemLynx/blob/master/docs/API.md#tasksjs-api-documentation) for the full middleware API.

---

# Architecture: Monolith to Microservices

One of the core ideas behind SystemLynx is that your module code doesn't change depending on how you deploy it. You can start with everything in a single service and scale it out later — without rewriting anything.

## Start as a monolith

```javascript
const { Service } = require("systemlynx");

Service.module("Users", Users);
Service.module("Orders", Orders);
Service.module("Products", Products);

Service.startService({ route: "api", port: 4400, host: "localhost" });
```

Your client loads everything from one place:

```javascript
const { Users, Orders, Products } = await Client.loadService("http://localhost:4400/api");
```

## Scale out: move modules to their own services

When you're ready to scale, pull any module into its own service. The module code is unchanged — just move it and update the URL the client loads from.

```javascript
// users-service.js
Service.module("Users", Users);
Service.startService({ route: "users", port: 4401, host: "localhost" });

// orders-service.js
Service.module("Orders", Orders);
Service.startService({ route: "orders", port: 4402, host: "localhost" });
```

```javascript
// client
const { Users } = await Client.loadService("http://localhost:4401/users");
const { Orders } = await Client.loadService("http://localhost:4402/orders");
```

Because every module can be hosted independently, you can scale horizontally (run multiple instances of a service) or vertically (split a busy module into its own service) as your needs grow.

## Load Balancing & Clustering

The **LoadBalancer** turns many identical instances of your services into one cluster —
service discovery, connect-time load balancing, and cluster coordination
(`delegate` / `broadcast` / `elect`). See **[LOADBALANCER.md](./docs/LOADBALANCER.md)** for the full guide.

Run a LoadBalancer:

```javascript
const { LoadBalancer } = require("systemlynx");

LoadBalancer.startService({ route: "loadbalancer", port: 4000 });
```

A service joins the cluster with the `clone` plugin — it auto-registers and installs
`this.clone` on every module:

```javascript
const { App, LoadBalancer } = require("systemlynx");

App.startService({ route: "orders", port: 4100 })
  .module("Orders", Orders)
  .use(LoadBalancer.clone({
    url: "http://localhost:4000/loadbalancer",
    serviceId: "Orders",
  }));
```

`serviceId` is the identity this service registers under, and it is required. Every member sharing
one becomes part of the same logical service, reachable at `<loadbalancer>/Orders`.

Now any module can coordinate across the cluster — e.g. run a task exactly once, no matter how
many clones are live:

```javascript
Orders.on("order_paid", async function (order) {
  const { delegated } = await this.clone.delegate(`receipt:${order.id}`);
  if (delegated) sendReceiptEmail(order); // one clone does it, not all of them
});
```

---
_Source: https://npm.io/package/systemlynx · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._
