repo layout

Pre-Alpha. This page describes behavior that may change.

The Ze repo is organised around three top-level Go directories (cmd/, internal/, pkg/) and a set of supporting directories for docs, tests, schemas, and tooling. This page is a fast tour. When you need more than a tour, the canonical map is main/CLAUDE.md.

The top level

main/
├── cmd/                  # Executables (programs)
├── internal/             # Unexported packages
├── pkg/                  # Exported packages (SDK surface)
├── docs/                 # In-tree documentation
├── rfc/                  # RFC indices and short extracts
├── plan/                 # Specs and design planning documents
├── test/                 # Functional test fixtures (.ci files)
├── scripts/              # Code generation and inventory tooling
├── third_party/          # Vendored third-party code
├── Makefile              # Every build and test target
├── README.md             # Project statement
├── CONTRIBUTING.md       # Contribution process
├── CLAUDE.md             # Project-specific Claude Code rules
└── CLA.md                # Contributor licence agreement

CLAUDE.md is the first file to read if you plan to touch the code. Everything else in this page is expanded from it.

The executables

Each subdirectory under cmd/ is a Go main package that produces one binary.

Binary	Purpose
ze	The daemon, CLI, SSH server, web UI, Looking Glass, MCP, and every subcommand.
ze-chaos	Chaos testing orchestrator.
ze-perf	Performance benchmarking.
ze-analyse	MRT and RIB analysis.
ze-test	Functional test driver.

make build produces four of these under bin/: bin/ze, bin/ze-test, bin/ze-chaos, and bin/ze-analyse. bin/ze-perf requires a separate make ze-perf target. make ze produces just the daemon.

internal

internal/ is the bulk of the codebase. Components are mostly independent, and they communicate through registration instead of imports.

Components

internal/component/ holds the subsystems. Each one has its own directory.

Directory	Subsystem
bgp/	The BGP engine: reactor, FSM, wire parser, peer lifecycle, message cache.
config/	Config loading, YANG parser, commit workflow, archive, validators.
cli/	The interactive shell and the editor state.
ssh/	The SSH server.
web/	The HTTPS web UI and the REST API handlers.
lg/	The Looking Glass server and the AS path graph renderer.
mcp/	The MCP server.
iface/	Interface management via netlink.
resolve/dns/	The built-in DNS resolver (under resolve/).
resolve/	DNS and other resolution backends.
telemetry/	Prometheus metrics.
cmd/	Command dispatch and execution.
command/	CLI command definitions.
engine/	The supervisor.
hub/	Plugin TLS transport and fleet management.
plugin/	Plugin lifecycle, registry, process manager.
managed/	Managed-mode client.
authz/	Authorisation.

The EventBus interface is defined in pkg/ze/eventbus.go, not in a separate component directory.

BGP plugins

The BGP plugins live in internal/component/bgp/plugins/. Each plugin is a self-contained directory with its register.go, its handler code, its YANG schema under schema/, and its tests.

internal/component/bgp/plugins/
├── rib/                  # bgp-rib
├── persist/              # bgp-persist
├── adj_rib_in/           # bgp-adj-rib-in
├── rs/                   # bgp-rs (route server)
├── gr/                   # bgp-gr (Graceful Restart, LLGR)
├── rpki/                 # bgp-rpki
├── rpki_decorator/       # bgp-rpki-decorator
├── role/                 # BGP Role (RFC 9234)
├── watchdog/             # bgp-watchdog
├── healthcheck/          # bgp-healthcheck
├── route_refresh/        # bgp-route-refresh
├── aigp/                 # bgp-aigp
├── hostname/             # bgp-hostname
├── softver/              # bgp-softver
├── llnh/                 # bgp-llnh
├── filter_community/     # filter-community
└── nlri/                 # bgp-nlri-* (EVPN, FlowSpec, VPN, BGP-LS, ...)

Infrastructure plugins

internal/plugins/ holds the non-BGP plugins: fibkernel, fibp4, ifacedhcp, ifacenetlink, sysrib. These register under the user-facing names fib-kernel, fib-p4, iface-dhcp, and rib respectively (the sysrib package registers the plugin named rib); ifacenetlink is a backend for the interface component.

Core

internal/core/ holds cross-cutting packages that do not belong to a single subsystem: the report bus, structured logging, the config environment, the registration helpers.

Chaos

internal/chaos/ holds the chaos testing orchestrator's reporter, scheduler, property validators, and web dashboard code. The CLI lives in cmd/ze-chaos/.

pkg

pkg/ is the exported surface. Anything here is meant to be importable from outside the repo.

Directory	Purpose
pkg/plugin/sdk/	The Go plugin SDK: NewFromEnv, Run, the On* callbacks, the engine calls.
pkg/plugin/rpc/	The plugin wire protocol (message framing, MuxConn).
pkg/ze/	Re-exports the stable Ze API surface.
pkg/zefs/	The blob-store filesystem used for config storage.
pkg/fleet/	The fleet manager client.

docs

In-tree documentation. The wiki adapts from here but does not replace it. Subdirectories:

• docs/guide/ - operator-facing guides.
• docs/features/ - per-feature reference.
• docs/architecture/ - deep architecture docs.
• docs/plugin-development/ - plugin SDK reference.
• docs/research/ - design research and analysis.
• docs/exabgp/ - ExaBGP comparison and migration notes.

test

Functional test fixtures, organised by category (decode/, editor/, encode/, hub/, integration/, internet/, interop/, managed/, parse/, perf/, plugin/, reload/, scripts/, stress/, ui/, web/, exabgp/, exabgp-compat/, chaos-web/, ...). Each test is a .ci file: a small scripting language for the functional test runner. ze-test consumes them.

scripts

Code generation and inventory tooling. scripts/codegen/plugin_imports.go generates the plugin import file that pulls every in-tree plugin into the binary. scripts/inventory/ generates make ze-inventory and make ze-command-list. scripts/docvalid/ runs make ze-doc-drift and make ze-validate-commands.

rfc

RFC references the project depends on, plus short extracts used for cross-checking.

plan

The spec directory. Every feature lands as a spec under plan/ before any code is written. plan/TEMPLATE.md is the template, and the maintainer's workflow is spec-first.

.claude

The project-specific Claude Code rules, patterns, and slash commands. .claude/rules/ holds the rules that apply to every contribution. .claude/patterns/ holds the "how to add a thing" patterns (CLI command, web endpoint, plugin, config option, etc.).

See also

• Building for the make targets.
• Contributing for the contribution workflow.
• Coding standards for the rules that land inside files.
• main/CLAUDE.md for the canonical repo map.

Adapted from main/CLAUDE.md.