Skip to Content

Contributing

Architecture

How Nexul is put together — one Go module, two adapters over a shared use-case layer, and everything around it.

Nexul is one Go module (github.com/otal-labs/nexul) that builds the nexul-server, nexul-runner and nexul (install and upgrade) binaries. The repository also contains a React web app, a thin Electron desktop shell, a TypeScript SDK with its own Bun CLI, and a small automations host compiled into nexul-automations. Keeping these surfaces in one repository makes the seams between them explicit.

The domain layer

Business logic lives under internal/<domain>/, one directory per bounded context — tickets, deploy, docs, topology, and so on. A domain owns its model, its storage interface, its use-cases, and the events it produces and consumes, and it never imports another domain directly. Most domains follow a five-file shape: model.go, repo.go, usecase.go, handler.go, events.go. Domains with no events yet, or a thinner shape, are exempt until they need it. See Repository layout for the full directory map.

Two adapters, one use-case layer

Every capability the product offers is a use-case function. Two adapters call it, and neither duplicates it:

  • HTTP/JSON gateway — what the browser talks to, and what a third-party integration talks to with a scoped API token instead of a session.
  • MCP server — the Model Context Protocol adapter LLM agents use to drive the product: search docs, create tickets, read topology, trigger deploys, replay a dead letter.

Capabilities belong in the use-case layer. A feature is not complete until both applicable adapters expose it. Neither adapter carries business logic of its own; each parses input, calls the use-case, and formats the output.

SQLite is the spine

One SQLite file, one writer, WAL mode for concurrent readers, FTS5 for full-text search over docs and tickets. Queries are written by hand in .sql files under internal/platform/storage/queries/, and sqlc compiles them into internal/platform/storage/sqlcgen/ against the migrations directory — no Postgres, no dual-backend abstraction.

The EventBus is the microservice seam

Domains that need to react to each other’s changes do it through the EventBus interface in internal/platform/eventbus/, never through direct imports. Today the bus is in-process and channel-backed — one process, zero network hops. If a domain ever needs to become its own service, the bus implementation swaps to NATS via Watermill and the domain code doesn’t change: it still calls Publish/Subscribe on the same interface. Critical events go through a transactional outbox, written in the same SQLite transaction as the domain change, so an event can never be lost or published for a change that rolled back.

The web app

web/ is React 19 + Vite + Tailwind, built with shadcn/ui components. It talks to the server over the HTTP/JSON gateway for requests and a WebSocket for live events — never over MCP; the browser never speaks JSON-RPC.

The phone app

native/ is an Expo app for Android and iPhone that talks to the same gateway and WebSocket. The rules both apps run, such as the permission table, chat and embed rules, and the reconnecting live socket, live once in client-core/ and are imported by both, so the two apps cannot drift.

Desktop

desktop/ is a thin Electron shell over the same served web app. It exists for consistent rendering on Linux, not to host a second UI: it bootstraps a connection token and otherwise stays out of the way.

SDK and automations

sdk/ is the TypeScript package automations are written against. It contains the API client, generated event types, config schema, testing surface, and a Bun CLI with nexul init, nexul dev, nexul push, and nexul pull. automations/ is the automations host: a small service that runs the automations placed on it. Every instance installs one named instance for the Default automations, and more can be installed on other machines.

Edit this page