Architecture Overview

Nexus OS is organized into strict architectural layers. Each layer has a single responsibility and communicates with adjacent layers through well-defined interfaces.

Layer Diagram

┌─────────────────────────────────────────────────┐
│                  Applications (NPK)              │
│            Firefox · KDE · User Programs         │
├─────────────────────────────────────────────────┤
│              NipCells / Nexters                   │
│         Lightweight & Heavy Isolation             │
├──────────┬──────────┬──────────┬────────────────┤
│ Surface  │ Signal   │ Membrane │  nip           │
│ Manager  │ Forge    │ (Net)    │  (Packages)    │
│ Display  │ A/V/R    │ TCP/IP   │  Graft/Build   │
├──────────┴──────────┴──────────┴────────────────┤
│              Capability Algebra                   │
│     Pledge · Unveil · CSpace · ProvChain          │
├─────────────────────────────────────────────────┤
│              ION Rings (IPC)                      │
│       Lock-free SPSC Ring Buffers                 │
├─────────────────────────────────────────────────┤
│              Rumpk Kernel                         │
│   Scheduler · Memory · SysTable · NetSwitch       │
├─────────────────────────────────────────────────┤
│              Zig HAL                              │
│   VirtIO · UART · GIC · Timer · MMU               │
├─────────────────────────────────────────────────┤
│              Rumkv Hypervisor                     │
│         Type-1 (EL2 / Ring-1 / M-Mode)           │
├─────────────────────────────────────────────────┤
│              nexus-boot                           │
│         Bootloader (<300 LOC)                     │
└─────────────────────────────────────────────────┘

Layer Responsibilities

Boot Layer

nexus-boot is a stripped Limine fork. Less than 300 lines of code. Multi-architecture. Gets the hardware to a known state and hands off to Rumkv or Rumpk. Optional Hall of Fame splash screen.

Hypervisor Layer

Rumkv is a Type-1 hypervisor operating at the highest privilege level (ARM64 EL2, x86 Ring-1, RISC-V M-Mode). It provides hardware isolation between guests and the Rumpk kernel. Verified with NetBSD ARM64 guests.

Kernel Layer

Rumpk is a 280KB event-driven unikernel. It provides:

• The Harmonic Scheduler with four time spectrums
• ION Rings for zero-copy IPC
• The SysTable — a fixed ABI contract at a physical address
• The NetSwitch — an L2 packet demuxer

The kernel has 12 fixed syscalls plus 1 meta-slot. It never changes.

Security Layer

The Capability Algebra provides 7 primitive verbs (SPAWN, SEND, RECV, MAP, MASK, TICK, GRANT). Every operation requires an explicit capability. Pledge/unveil restricts processes to minimum privilege. The Kinetic Economy prevents DoS through energy budgets. ProvChain logs everything.

IPC Layer

ION Rings are lock-free single-producer/single-consumer ring buffers. All inter-process communication flows through them. Zero-copy. No locks. No contention.

Service Layers

• Membrane — Userland TCP/IP (grafted LwIP) + sovereign UTCP transport
• Surface Manager — Sovereign compositor with zero-copy rendering
• SignalForge — Audio, video, and radio signal processing
• nip — Universal package manager with grafting from any ecosystem

Application Layer

Applications run as NPK (Nip Packages) inside NipCells (lightweight isolation) or Nexters (heavy containers with namespace/jail/VM isolation). Every application is sandboxed. Every binary is signed.

Design Principles

The Kernel Delivers the Mail; It Does Not Read the Letter

The kernel is deliberately minimal. TCP/IP processing, filesystem logic, and display composition all live in userland services. If any service crashes, the kernel survives and restarts it.

Data Moves, Code Stays

CPU cores are isolated. Data flows through ION Rings between fibers. No shared-memory concurrency. No mutex soup. Linear scaling to 256+ cores via DragonflyBSD LWKT message-passing.

Graft What Works, Harden Later

Nexus strategically borrows from Linux (drivers), OpenBSD (security primitives), NetBSD (rump kernels), and Alpine (musl/busybox) — wrapping everything in sovereign abstractions. Foreign code is sanitized, pledged, and frozen into deterministic packages.

One Codebase, Many Targets

The build toolkit reads KDL blueprints and produces bootable images for any target profile. The same code compiles down to a 256-byte sensor firmware or a 40MB cluster node. Feature flags control what gets included.

Component Map

Component	Language	Size	Status
Rumpk	Nim + Zig	280KB	v0.9 Complete
Rumkv	Nim + Zig	—	ARM64 EL2 Complete
NexFS	Zig	—	v0.3.0 (51/51 tests)
Membrane	Nim	—	Operational
UTCP	Zig	~200 LOC	Integrated
LWF	Zig	~15K LOC	24/24 test suites
nip	Nim	—	MVP Complete
nexus-boot	—	<300 LOC	v1 Complete
nexus build	Nim	~2MB	~50% Complete