Technical overview

The engineering view of each component — what it does, what stack it runs, and where the seams are. For the one-screen visual, see Architecture. For repository/library breakdown, see Repositories.

Components

Component	Tech	Role
nexus-core	Rust, axum, tokio, MongoDB	Orchestration API + the only authority over state.
nexus-worker	Rust, tokio, async-nats, MongoDB	Scheduling, dispatch, retries, Plane sync, reconciliation.
nexus-agent-runner	Rust, reqwest, duct	Generic runtime: one image becomes any agent from a config payload.
nexus-telegram	Rust, teloxide	High-level command gateway.
nexus-ui	Next.js 16, React 19, Tailwind v4, TanStack	Admin dashboard (separate repo).
crates	Rust	Shared libraries with the trait seams.

What ties them together

                         nexus-ui (Next.js)
                              │ REST (via /api/nexus proxy)
                              ▼
                        nexus-core (axum)
              ┌───────────────┼───────────────┐
              │ MongoDB       │ NATS          │ Kubernetes
              ▼               ▼               ▼
         state (truth)   events (durable)  agent Jobs
              ▲               ▲               │
              │               └───────────────┘ events back
              │                                 from runner pods
        nexus-worker  ◀── consumes events, schedules, syncs to Plane

Nexus Core is the only component that writes the source of truth. The worker reacts to events and reconciles. The runner is stateless and ephemeral.

Reading order

• nexus-core — start here for the API surface and the orchestration engine.
• nexus-agent-runner — how a config payload becomes an execution.
• nexus-worker — scheduling, retries, and board sync.
• crates — the trait seams (AgentRuntime, BoardProvider, LlmProvider).
• nexus-ui — the admin pages.
• nexus-telegram — the command gateway.

Public vs internal documentation

Nexus publishes two views of these docs. The internal build adds implementation-detail pages (sprint plans, attack-surface analysis, runbooks with credential paths) under docs/_internal/**. Public docs reference them by name but do not link to them.