Ze Architecture

A one-page guide to how Ze is structured. For the full design document with rationale, wire format details, and performance analysis, see DESIGN.md. For the canonical architecture reference, see architecture/core-design.md.

What Ze Is

Ze is a network operating system built in Go. A small, protocol-agnostic engine supervises a message bus, a config provider, and a plugin manager. The engine has no knowledge of BGP or any specific protocol. BGP, interface management, firewall, traffic control, and everything else register as subsystems and plugins.

Component Map

Engine (supervisor, lifecycle, config)
  |
  +-- Hub / Bus (content-agnostic message routing, []byte on hierarchical topics)
  |     |
  |     +-- BGP Subsystem (TCP, FSM, wire parsing, capability negotiation, reactor)
  |     +-- Interface component (netlink/VPP backend, DHCP, NTP)
  |     +-- Firewall component (nftables/VPP backend)
  |     +-- Traffic component (tc/VPP backend)
  |     +-- Config provider (YANG-parsed tree, transaction protocol)
  |     +-- Plugin infrastructure (registry, process manager, DirectBridge)
  |           |
  |           +-- bgp-rib, bgp-rs, bgp-gr, bgp-role, and many more
  |           +-- fib-kernel, sysrib, static, sysctl, ...
  |           +-- External plugins (any language, TLS connect-back)
  |
  +-- CLI (SSH-accessible editor and command shell)
  +-- Web UI (HTMX-based config editor, admin dashboard, SSE live updates)
  +-- Looking Glass (peer/route viewer, birdwatcher-compatible API)
  +-- Telemetry (Prometheus metrics, optional Basic Auth)
  +-- MCP server (Model Context Protocol for AI tool integration)

Key Design Choices

Key Wire Abstractions

Hub / Bus

The bus is the central notification router. It routes opaque []byte payloads on hierarchical topics (e.g., bgp/update, interface/up) with prefix-based subscription matching. It is used for broadcast state changes and event fan-out; request/response calls use the plugin dispatcher, DirectBridge, or typed package interfaces. The bus never inspects payload content.

Components avoid importing each other's implementation packages. They communicate through registries, bus topics, plugin RPC, DirectBridge, or shared core value types depending on the direction and latency requirements. BGP subscribes to interface events to react when addresses appear or disappear. The FIB pipeline uses bus topics to carry best-path decisions from BGP RIB through system RIB to kernel route installation.

BGP Subsystem

The BGP subsystem owns the protocol: TCP connections, FSM state machines, wire parsing, capability negotiation, and the reactor event loop. It produces structured events and consumes commands. It never imports plugin code.

For a walk-through of the BGP state machine, see bgp-fsm.md.

Configuration

JUNOS-like hierarchical syntax: {} blocks, ; terminators, # comments. YANG-driven parsing. Three-level inheritance: BGP globals, group defaults, peer overrides. Configuration is stored in ZeFS (a blob store with commit/rollback) and managed through an interactive editor accessible over SSH.

For the full config syntax reference, see config-reference.md.

Plugin Architecture

All features beyond core engine operation are plugins: RIB storage, route reflection, graceful restart, RPKI validation, NLRI encoding, FIB programming, firewall, traffic control, and more. Plugins run in-process (goroutine + DirectBridge) or as external processes (TLS connect-back in any language).

For the plugin architecture overview, see plugin-overview.md. For writing plugins, see plugin-development/.

Data Flow

Receive:  Network -> WireUpdate -> Reactor -> EventDispatcher -> Plugins
Announce: Text command -> ParseUpdate() -> WireUpdate -> Peer
Forward:  Cache lookup -> Egress filters -> Wire (zero-copy when ContextID matches)

The reactor fires a single StructuredEvent per received UPDATE. Forwarders (route server, route reflector) and state trackers (RIB plugin) both subscribe to the same dispatch but consume it differently: forwarders make per-peer forwarding decisions, state trackers update best-path state.

FIB Pipeline

Best-path decisions flow through the bus:

1. BGP RIB detects best-path changes, publishes to bgp-rib/best-change/bgp
2. System RIB selects system-wide best by administrative distance, publishes to system-rib/best-change
3. FIB Kernel programs OS routes via netlink (RTPROT_ZE=250)

Programs

Source Layout

Deeper Reading