Architecture Overview

Status: Current

Last reviewed: 2026-05-16

Repositories

NexusNet is currently split into three code repositories plus this docs repository:

• nexus-backend: Rust control plane, REST API, secure gRPC agent control, PostgreSQL storage, route deployment logic, credentials, and dashboard data.
• nexus-agent: Rust node agent, L4 gateway, TCP/UDP forwarding, Noise/REALITY credentials, TCP REALITY, Quinn-based QUIC REALITY, QUIC DATAGRAM, L3 TUN dataplane, and metrics.
• nexus-frontend: Next.js dashboard for nodes, L3 tunnels, L4 chains, upstreams, security credentials, audit, users, and settings.
• nexus-docs: canonical documentation.

Control Plane

The control plane is implemented by nexus-backend.

Main responsibilities:

• REST API under /api.
• JWT authentication and RBAC.
• PostgreSQL schema migrations.
• Node authentication and heartbeat over the secure agent control stream.
• Agent config streaming with DB-backed RuntimeConfigSnapshot messages inside encrypted control frames.
• Agent-reported runtime listener state for /api/nodes/ports/runtime.
• L4 chain persistence and deployment.
• L3 tunnel persistence and deployment.
• Upstream, TLS certificate, and encryption credential management.
• Dashboard stats and audit log APIs.

Current backend runtime:

• Rust edition 2024.
• Axum for REST.
• Tonic for gRPC.
• SQLx with PostgreSQL.
• Redis is present in compose for supporting services/rate-limiting evolution.

Agent Plane

The agent is implemented by nexus-agent.

Main responsibilities:

• Authenticate with the backend over the secure control stream.
• Maintain heartbeat and receive config frames.
• Run in-process gateway listeners for TCP, UDP, TLS, REALITY, and Quinn-based QUIC REALITY paths.
• Apply TcpProxyRule, UdpRule, QuicRule, L3TunnelRule, upstream clusters, and TLS certificates from backend config.
• Merge same-port route tables when traffic can be separated by SNI, REALITY short ID, UDP Noise key, QUIC Initial detection, or RAW fallback rules.
• Report metrics snapshots and runtime listener tables.

Important agent modules:

• src/gateway/mod.rs: gateway orchestration and tests. The protobuf still names the L4 config envelope PingoraConfig, but the current repository does not depend on a separate Pingora crate.
• src/gateway/udp.rs: UDP session forwarding, Noise, and QUIC REALITY DATAGRAM upstream path, including shared UDP socket dispatch for embedded QUIC REALITY routes.
• src/gateway/crypto.rs: Noise/ENC helpers.
• src/gateway/quic.rs: Quinn-based QUIC REALITY listener, client pool, stream forwarding, DATAGRAM forwarding, L3 DATAGRAM context registry, and metrics.
• src/l3/*: L3 TUN, routing, packet, dataplane, transport, and metrics support.
• crates/reality-core: REALITY/TLS primitives.
• crates/reality-io: TCP REALITY stream/session helpers.
• crates/quinn-reality: Quinn crypto trait bridge for REALITY authentication.

Frontend

The frontend is implemented by nexus-frontend.

Current dashboard pages:

• Login.
• Dashboard.
• Nodes.
• Gateway L3 tunnels.
• Gateway L4 chains.
• Gateway L4 upstreams.
• Gateway security credentials.
• Audit.
• Settings and users.

Current Data Plane

Current supported or actively implemented paths include:

• TCP over TCP RAW.
• TCP over TCP TLS.
• TCP over TCP REALITY.
• UDP over UDP RAW.
• UDP over UDP Noise.
• TCP over QUIC REALITY.
• UDP over QUIC REALITY DATAGRAM.
• IP over QUIC REALITY DATAGRAM for managed L3 point-to-point tunnels.

The planned hand-written quic-core runtime path has been superseded by the Quinn-based implementation in crates/quinn-reality and src/gateway/quic.rs.

Planned paths are tracked in Transport Composition.

L3 Direction

Layer 3 work is implemented as an initial QUIC L3 control-plane and agent path:

• TUN/netdevice-facing L3 tunnel semantics.
• IP packets over QUIC REALITY DATAGRAM.
• Reliable control plane for route, MTU, and state.
• Future project-level Kernel DCO path for high-throughput TCP, UDP, QUIC, and L3 dataplane work.

See:

• QUIC L3
• NexusNet Kernel DCO
• Runtime Config Hot Reload