Skip to main content

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​

LibraryUse
axumHTTP API (ergonomic routing, extractors, Tower middleware)
tokioasync runtime
tower-httpCORS, tracing, compression, middleware
serde / serde_jsonJSON DTOs
anyhow / thiserrorerrors
tracinglogs / spans
utoipaOpenAPI generation
jsonwebtokenadmin JWT auth
argon2password hashing for local admin users
validatorrequest validation

Shape​

// apps/nexus-core/src/main.rs (sketch)
#[tokio::main]
async fn main() -> anyhow::Result<()> {
    nexus_observability::init("nexus-core");
    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_taiga::TaigaBoardProvider::new(
        TaigaConfig {
            base_url: cfg.taiga_base_url,      // https://taiga.nexusapp.dev
            // service-account login or a static auth_token (Bearer)
            auth: TaigaAuth::Credentials { username: cfg.taiga_user, password: cfg.taiga_password },
            project_id: cfg.taiga_project_id,
        },
    );

    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/.