osvbng context

Architecture decisions, design notes and working rules for osvbng. Rides as a submodule of the main repo; LLM-assisted contributors start with CLAUDE.md here before touching anything in the tree.

Layout

• CLAUDE.md - rules for LLM sessions: workflow, engineering rules, writing style. The entry point.
• decisions/ - ADRs, numbered and append-only. Index below.
• design/ - living design notes for things being built.
• references/ - protocol spec texts (RFCs). Protocol code is written with these open and cites sections.
• todo.md - the working queue between sessions.
• scripts/check-adr-index.sh - CI check that this index is complete.

Decisions

ADR	Title	Status
0001	Three-repo topology with public, LLM-first context	Accepted
0002	VPP built from pinned source with a maintained patch queue	Accepted
0003	One session setup primitive with opdb as authoritative inventory	Accepted
0004	Subscriber classification in a dedicated IPoE input node	Accepted
0005	Control-plane VRF isolation via LCP network namespaces	Accepted
0006	CGNAT port-block allocation architecture	Accepted
0007	CPU partitioning config expresses intent, not core IDs	Accepted
0008	Async VPP binary API transport with reconciliation in the session layer	Accepted
0009	Typed telemetry registry as the only metrics path	Accepted
0010	Gateway ARP and ND answered in the dataplane, SRG state convergent	Accepted
0011	LCP echo answered and generated in the osvbng_pppoe plugin	Accepted
0012	Go plugins are in-tree, pkg/ is not an external SDK	Accepted

Design notes

Doc	Topic
osvbng-implemented-summary	Orientation summary of the implemented system
vpp-dataplane	How VPP moves packets, code-grounded against the pinned version
control-dataplane-seam	Responsibility split between the Go control plane and VPP plugins
subscriber-access-model	Access handover shapes, per-subscriber interfaces, IP bindings
aaa-provisioning-model	Provisioning-first AAA, attribute model, service groups
qos-architecture	Per-subscriber policers and CAKE scheduling
qos-aggregates	Hierarchical aggregate shaping: subscriber, S-VLAN, port
ha-architecture	SRGs, virtual MAC failover, session sync, opdb, recovery
wholesale-l2gw	L2 wholesale gateway: circuits, VLAN rewrite, handoff groups
frr-evpn-capability-audit	Empirically verified FRR 10.7 EVPN behavior
routing-frr-bridge	How osvbng drives FRR: vtysh wrappers, show registry, telemetry cost rules
cgnat-architecture	CGNAT control/dataplane split, lifecycle, persistence and HA
cgnat-worker-model	How CGNAT should distribute across workers: nat44-ed prior art, the candidate, the test plan
cgnat-audit-2026-08	Verified findings of the August 2026 CGNAT audit, ranked, with the fix order
dead-code-audit-2026-08	Verified findings of the August 2026 dead code audit, the defects it surfaced, and the sign-off table gating each action
l2tp-architecture	L2TPv2 LAC and LNS: control-plane layout and the dataplane seam
pppoe-architecture	PPPoE termination: discovery, PPP machinery, echo at scale, HA replay
verification	How changes are verified: the local containerlab and bngblaster suites
ipoe-v6-dataplane-gap	Closed: mgmt-network route race behind the IPoE v6 suite flakes, and the false trails
telemetry	Metric flow: the typed registry, emission models, exporters, cardinality
performance-and-logging	Hot-path concurrency and logging rules, grounded in profiling evidence