Skip to Content

Contributing

Repository layout

What lives where in the Nexul monorepo.

Everything ships from one repository. This is what each top-level directory holds.

PathWhat lives there
cmd/nexul/The nexul command that installs, upgrades and removes Nexul’s services on a machine; its logic lives in internal/install/.
server/The nexul-server binary’s composition root (cmd/main.go) and its development Dockerfiles; wires domains and platform packages together.
runner/The nexul-runner binary — connects out to the server over WebSocket and executes builds and deploys on its host.
internal/Every domain package (internal/<domain>/) plus internal/platform/ (eventbus, storage, logging, config) shared by the binaries.
web/The React app served to the browser — Vite, Tailwind, shadcn/ui — talking to the server over the HTTP/JSON gateway and a WebSocket.
client-core/The modules the web app and the phone app both run (permissions, chat and embed rules, the live socket), imported as @nexul/client-core/<module>.
desktop/The Electron shell that wraps the served web app for a native-feeling install.
sdk/The TypeScript package automations are written against — client, API client, generated event types, config schema.
automations/The automations host, compiled into the nexul-automations binary, that runs the automations placed on it.
docs/adr/ — every durable decision, one file each; agents/ — how the tracker and the glossary are used. The glossary itself is CONTEXT.md at the root.
.scratch/The issue tracker — markdown files committed to the repo, one directory per effort, each with its spec and tickets.
website/This documentation site — Astro with Fumadocs UI.
practices/The coding standard, one file per language or surface. AGENTS.md routes each task to the file it needs.

See Architecture for how these pieces relate to each other, and Coding standards for the rules that govern what goes inside server/, internal/, and web/.

Edit this page