NexusLinkNexusLink Docs

End-to-end flows

Three cross-module mermaid diagrams. Each per-module guide repeats the slice that's relevant to its own scope — these are the canonical top-down views.

Flow A — Config → runtime (synth + deliver)

How an operator's change to a Provider, Policy, Guardrail, Budget Rule, or Settings record ends up as live middleware on a peer's proxy.

sequenceDiagram
    autonumber
    actor Op as Operator
    participant UI as Dashboard
    participant HTTP as management/handlers
    participant Mgr as agentnetwork.Manager
    participant Store as management/store (SQL)
    participant Ctl as network_map.Controller
    participant Synth as agentnetwork.SynthesizeServices
    participant Grpc as management gRPC
    participant Proxy as nexuslink-proxy
    participant Xlate as middleware_translate
    participant Chain as middleware.Chain

    Op->>UI: edit provider/policy/budget/settings
    UI->>HTTP: REST PUT/POST /api/agent-network/*
    HTTP->>Mgr: SaveProvider / SavePolicy / SaveBudgetRule / SaveSettings
    Mgr->>Store: persist (gorm)
    Mgr-->>Ctl: account change event (Network-Map dirty)
    loop per connected peer
        Ctl->>Synth: SynthesizeServices(ctx, store, accountID)
        Synth->>Store: load providers, policies, guardrails, budget rules, settings
        Synth-->>Synth: build per-peer Service list
        Note over Synth: each Service has a middleware<br/>chain with capture_prompt /<br/>capture_completion / redact_pii<br/>baked from account settings
        Synth-->>Ctl: []rpservice.Service
        Ctl->>Grpc: NetworkMap push (services + middleware configs)
    end
    Grpc-->>Proxy: NetworkMap stream
    Proxy->>Xlate: translate proto MiddlewareConfig → runtime Spec
    Xlate->>Chain: register / replace per-service chain
    Note over Chain: chain replacement is live<br/>(no proxy restart, in-flight<br/>requests unaffected)

Notes on the diagram

Flow B — Request lifecycle through the LLM chain

What happens when an agent on the client peer sends a chat-completion / messages request through the synthesised reverse-proxy.

sequenceDiagram
    autonumber
    actor Agent as Agent (local)
    participant Px as nexuslink-proxy
    participant Auth as auth middleware
    participant Map as service-mapping
    participant Req as llm_request_parser
    participant Rt as llm_router
    participant Chk as llm_limit_check
    participant Inj as llm_identity_inject
    participant Grd as llm_guardrail
    participant Up as upstream LLM
    participant Resp as llm_response_parser
    participant Cost as cost_meter
    participant Rec as llm_limit_record
    participant Log as access-log
    participant MgmtGrpc as management gRPC

    Agent->>Px: POST /v1/chat/completions  (OpenAI / Anthropic)
    Px->>Auth: identify peer (user, groups)
    Auth->>Map: resolve service from Host + path
    Map-->>Req: dispatch chain in slot order

    Req->>Req: parse body → provider, model, prompt, token estimate
    Note over Req: capture_prompt gates raw_prompt<br/>capture (nil = legacy emit,<br/>false = drop, true = emit)
    Req->>Rt: pass metadata
    Rt->>Chk: route to upstream candidate

    Chk->>MgmtGrpc: CheckLLMPolicyLimits(provider, model, est_tokens, groups, user)
    MgmtGrpc-->>Chk: decision = allow / deny + deny_code
    alt decision == deny
        Chk-->>Log: emit access-log with deny_code<br/>(if EnableLogCollection)
        Chk-->>Agent: 429 (or 403 per deny_code)
    else decision == allow
        Chk->>Inj: continue
        Inj->>Inj: inject NexusLink identity headers per provider config
        Inj->>Grd: continue
        Grd->>Grd: enforce per-provider allowlist (fail-closed backstop)
        Grd->>Up: forward (over WireGuard)
        Up-->>Resp: response (JSON or SSE stream)
        Resp->>Resp: parse usage tokens, completion
        Note over Resp: capture_completion gates raw<br/>completion capture
        Resp->>Cost: tokens
        Cost->>Cost: lookup rates from config-delivered<br/>pricing table + compute cost
        Cost->>Rec: tokens + cost
        Rec->>MgmtGrpc: RecordLLMUsage(provider, model, prompt_t, completion_t, cost, groups, user)
        Rec-->>Log: emit access-log entry<br/>(if EnableLogCollection)
        Log-->>Agent: 200 + body (streamed if SSE)
    end

Notes on the diagram

Flow C — Budget rule feedback loop

How an account's budget rules tighten ceilings on every request and how consumption flows back into the dashboard.

flowchart LR
    subgraph Operator
      DashBud[Dashboard Budget Settings tab]
    end
    subgraph Mgmt[Management]
      Save[POST/PUT /api/agent-network/budget-rules]
      Store[(SQL store)]
      Synth[SynthesizeServices]
      Check[CheckLLMPolicyLimits RPC]
      Rec[RecordLLMUsage RPC]
      Cons[/api/agent-network/consumption]
    end
    subgraph Proxy[Proxy]
      Chk[llm_limit_check]
      RecMw[llm_limit_record]
    end
    subgraph DashView[Dashboard Budget Dashboard tab]
      Panel[AgentConsumptionPanel]
    end

    DashBud -->|create / update rules| Save
    Save --> Store
    Store --> Synth
    Synth -->|push synth-services to peer| Proxy

    Chk -->|per request| Check
    Check -->|aggregate matching rules<br/>min-wins all-must-pass| Store
    Check -->|allow / deny| Chk

    RecMw -->|post-response| Rec
    Rec -->|tokens + cost + groups + user| Store

    Store -->|read counters| Cons
    Cons --> Panel

Notes on the diagram

Cross-references