nexus-core

The main HTTP API and the orchestration authority. It is the only component that mutates the source of truth.

Responsibilities

• Admin API · Agent API · Board API · Skill API · Memory API · Webhook API
• Auth · Approvals · Task orchestration
• Kubernetes job launcher (via nexus-k8s)

Stack

Library	Use
axum	HTTP API (ergonomic routing, extractors, Tower middleware)
tokio	async runtime
tower-http	CORS, tracing, compression, middleware
serde / serde_json	JSON DTOs
anyhow / thiserror	errors
tracing	logs / spans
utoipa	OpenAPI generation
jsonwebtoken	admin JWT auth
argon2	password hashing for local admin users
validator	request validation

Shape

// apps/nexus-core/src/main.rs (sketch)
#[tokio::main]
async fn main() -> anyhow::Result<()> {
    nexus_observability::init();
    let db = nexus_db::connect(&cfg.mongodb_url).await?;
    let events = nexus_events::connect(&cfg.nats_url).await?;
    let runtime = nexus_k8s::KubernetesAgentRuntime::new(/* ... */)?;
    let board = nexus_board_plane::PlaneBoardProvider::new(/* ... */);

    let app = router(AppState { db, events, runtime, board });
    axum::serve(listener, app).await?;
    Ok(())
}

Why axum

axum is designed around ergonomic routing, extractors, and Tower middleware — a strong fit for a service that exposes many namespaced API scopes and shares state across handlers.

Endpoints

The conceptual model, scopes, and examples live in the API reference. OpenAPI is generated by utoipa and served at /swagger-ui/.

Related

• crates — the trait seams Core wires together
• API reference
• nexus-worker — the background half