NEXUS is the in-house communications and coordination product that replaces Discord for internal humans, Symbiotes, Curators, and supporting systems.
- Desktop-first and local-first
- Managed local NEXUS service on the workstation
- Shared service contract for desktop now and web later
- Communications core only in the first executable MVP
- Tight early coupling with
ANVIL - Discord treated as a temporary adapter, not the product model
- Product:
NEXUS - Database estate:
LIBRARY - Communications/event record layer:
CHATBASE - Metadata, registry, and policy layer:
METABASE
apps/serviceLocal NEXUS service with REST endpoints, bootstrap loading, CHATBASE/METABASE scaffolding, and adapter ingress.apps/desktopElectron desktop shell that manages the local service, logs managed-runtime failures, and loads the local web surface.apps/webBrowser-facing NEXUS client that uses the same service contract for channel browsing, direct conversations, forum posts, native threads, search, and composition.packages/contractsShared entity kinds and input validators for the MVP contract.config/internal-bootstrap.jsonGreenfield internal channel and workspace bootstrap for private and shared spaces.
npm install
npm run service:start
npm run service:library
npm run import:chatbase
npm run desktop:start
npm testThe current desktop implementation in this repo is the Electron-managed shell in apps/desktop backed by the Node service in apps/service.
This repo does not currently contain an Avalonia desktop client. Any future native-desktop or Avalonia transition would be a new implementation decision rather than the current repo baseline.
The April 1, 2026 direction for future NEXUS desktop work is:
- native-C-first runtime and interop surfaces
- Avalonia as the desktop UI host where a managed shell is still useful
- native C interop as the preferred boundary between the UI host and native runtime components
- C# only where necessary for Avalonia hosting, glue code, or thin orchestration layers
- C++ only for narrowly justified component internals when Native C is not viable, hidden behind the Native C boundary
- NEXUS as a container interface for surface programs and approved helper programs, not a monolithic rewrite of imported runtimes
That means Electron and the current Node-managed desktop shell should be treated as the continuity baseline already present in repo, not the intended long-term desktop stack.
The bounded architecture contract is recorded in docs/architecture-contract.md. The runtime container interface for component programs is recorded in docs/runtime-container-interface.md.
The service now supports two persistence modes behind the same contract:
jsonBootstrap/runtime convenience mode usingruntime/metabase.jsonandruntime/chatbase.jsonlibrary-postgresLIBRARY-backed persistence mode that writes NEXUS-native records into separateCHATBASEandMETABASEschemas in Postgres
Environment keys for library-postgres mode:
$env:NEXUS_STORAGE_MODE = 'library-postgres'
$env:NEXUS_LIBRARY_CONNECTION_STRING = 'postgres://...'
$env:NEXUS_LIBRARY_CHATBASE_SCHEMA = 'nexus_chatbase'
$env:NEXUS_LIBRARY_METABASE_SCHEMA = 'nexus_metabase'The product contract stays the same across both modes. JSON is only the bootstrap backend; LIBRARY-backed persistence is the intended long-term path.
The same service can now run in two runtime shapes without forking the API model:
local-managedThe desktop-first default. The service binds to localhost, serves the bundled client surface, and is managed by the desktop shell.hostedA hosted-capable mode for non-local deployment. Host/bind/public-origin settings are explicit, CORS can be enabled for a separate web surface, and static serving can be disabled for API-only operation.
Relevant config keys:
{
"deploymentMode": "hosted",
"host": "0.0.0.0",
"port": 43100,
"staticMode": "disabled",
"publicOrigin": "https://nexus.example.invalid",
"allowedOrigins": ["https://nexus.example.invalid"]
}The desktop shell now treats the managed local NEXUS service as an explicit runtime with operator-visible diagnostics rather than a silent child process:
- it verifies a usable Node.js binary before launch
- it reuses an already-healthy local NEXUS service on the configured localhost port instead of blindly double-starting
- it writes managed-service stdout and stderr to a runtime log under the desktop user-data path
- it surfaces launch and readiness failures through the desktop shell with a stable error code and log-path context
- it stops owned managed-service children cleanly on app quit
The current desktop/web client can:
- browse visible workspaces and channels
- open and create direct conversations between internal identities
- open forum-style channels as native post lists
- open and create native threads under channels and posts
- read imported Discord history from NEXUS-native channels and posts
- browse imported and newly created attachment metadata inline with messages
- create forum posts and ordinary messages with inline attachment metadata through the same service contract
- browse and create external references on scopes and selected messages for ANVIL, GitHub, or Discord-linked context
- run a read-only reverse lookup for an ANVIL, GitHub, or Discord external item, search the already-loaded readable results, group and filter them by owner type, see scope/message coordination summaries for each readable result, and jump directly into each linked NEXUS channel, post, thread, direct conversation, or message
- inspect and create relay and handoff records for the current scope, switch the coordination rail into a selected-message focus when needed, jump back to related messages when coordination records carry
messageId, and see message-level coordination badges directly in the conversation view - keep the URL in sync with the current actor, workspace, scope, and selected-message context so operators can deep-link directly back into readable NEXUS state
- copy a readable link to the current scope or the currently selected message directly from the client surface
- render clickable breadcrumbs for the current workspace, scope, and selected-message route so operators can step back through readable context without relying only on the sidebar
- keep a recent readable route-history stack in the client, with in-surface back and forward controls for stepping through recent NEXUS context without leaving the current surface
- surface recent readable activity across channels and direct conversations so operators can see what changed recently and jump back into the relevant NEXUS route state
- search visible history and jump into matching channel, post, thread, or direct scopes
For normal local use, copy config/nexus.local.example.json to config/nexus.local.json and fill in the real LIBRARY connection details. The service and desktop shell will pick that file up automatically.
If local library-postgres credentials are not valid yet, switch to JSON bootstrap mode for isolated local runs instead of treating a failed desktop launch as an application-surface bug:
{
"storageMode": "json"
}npm run import:chatbase imports retained Discord history from the existing LIBRARY chatbase schema into NEXUS-native records using the active Discord adapter channel mappings. The first importer pass is intentionally bounded to adapter-mapped channels, so it brings over known lanes without redefining NEXUS access policy.
The importer now also carries retained Discord forum posts into native NEXUS posts when the retained source only preserves thread-channel rows. Those forum posts are routed through explicit bootstrap rules so investigation-style posts land in investigation, issue-style posts land in report, and unmatched retained forum posts fall back to library instead of being dropped.
When retained Discord event payloads preserve a thread parentId, the importer now uses that recovered parent mapping as the authoritative source for the target NEXUS forum lane and only falls back to forum-routing rules when the retained source genuinely lacks parent metadata.
The importer also derives durable relay records for imported Discord messages. That backfills cutover diagnostics into already-imported NEXUS history instead of limiting relay visibility to fresh adapter traffic only.
Live POST /api/adapters/discord/events ingress now persists a relay record for every accepted Discord message and may persist an accompanying handoff record when the adapter payload includes a handoff object. The cutover diagnostics surface is therefore backed by durable CHATBASE records, not sidecar logs.
- First-pass architecture brief
- MVP service contract
- CHATBASE and METABASE storage contract
- ANVIL integration contract
- Discord cutover plan
- Hosted service mode
- Architecture contract
- Runtime container interface
- Runtime topology
- First runtime migration seam
- Runtime package manifests
- Conversation-surface program model