Architecture
Crate dependency graph, workspace layout, and design patterns powering the Helix kernel.
Architecture
Helix is a modular hybrid kernel written entirely in Rust. Instead of a monolithic blob or a pure message-passing kernel, Helix organizes every subsystem as a loadable module behind trait-based interfaces. This architecture gives you the performance of in-kernel calls with the flexibility to hot-swap any component at runtime.
The workspace is split into 12 crates, each with a single responsibility. Understanding their dependency graph is key to working with the framework.
Crate Dependency Graph
Every crate in Helix has a clear role and well-defined boundaries. The dependency flow is strictly top-down — no circular references allowed.
| Crate | Role | Depends On |
|---|---|---|
helix-core | Kernel core — orchestrator, IPC, syscalls, hot-reload, self-healing | helix-hal |
helix-hal | Hardware Abstraction Layer — CPU, MMU, interrupts, firmware | — (leaf crate) |
helix-boot | Boot protocols — Limine, Multiboot2, early init, KASLR | helix-core, helix-hal |
helix-modules | Module framework — traits, registry, loader, ABI, interfaces | helix-core |
helix-fs | HelixFS virtual filesystem — VFS, journal, snapshots, crypto | helix-core |
helix-memory | Memory subsystem — physical allocator, virtual mapper, heap, slab | helix-hal |
helix-execution | Execution — scheduler trait, threads, processes, context switch | helix-core |
helix-dis | Dynamic Intent Scheduling — intent classes, security domains | helix-execution |
helix-init | Init subsystem — 8-phase boot, subsystem registration | helix-core |
helix-nexus | NEXUS AI framework — prediction, self-healing, performance tuning | helix-core |
helix-userspace | Userspace — ELF loader, shell, syscall table, runtime | helix-core, helix-fs |
drivers/gpu | MAGMA GPU driver — framebuffer, acceleration | helix-hal |
Profile System
A profile is a complete kernel configuration. Each profile lives in its own directory under profiles/ and defines everything — allocator, scheduler, boot protocol, debug flags, and linker script. You can ship entirely different kernels from the same codebase by simply switching profiles.
| Profile | Boot Protocol | Scheduler | Allocator | Description |
|---|---|---|---|---|
default | Limine | Round-Robin | Buddy | General-purpose balanced configuration |
minimal | Multiboot2 | FIFO | Bump | Smallest possible footprint — CI and testing |
server | Limine | DIS | Buddy | Server workloads with intent-aware scheduling |
desktop | Limine | DIS | Buddy + Slab | Interactive desktop with low-latency tuning |
embedded | Direct | Priority | Bitmap | Resource-constrained embedded targets |
testing | Limine | Round-Robin | Buddy | Full debug symbols, assertions, sanitizers |
Design Patterns
Helix follows strict design patterns across every crate. Understanding them will help you navigate the codebase and write idiomatic extensions.
| Pattern | Where Used | Why |
|---|---|---|
| Trait-first interfaces | HAL, Scheduler, Allocator, FileSystem | Swap implementations without changing callers |
| Newtype IDs | ThreadId(u64), ProcessId(u64), InodeId(u64) | Prevent mixing up ID types at compile time |
| Bitflags | PageFlags, OpenFlags, ModuleFlags, ThreadFlags | Type-safe bit manipulation with readable names |
Lazy<T> singletons | Registries, router, scheduler framework | Safe late-initialization for kernel globals |
| Multi-arch via HAL | CPU, MMU, Interrupts, Firmware | Add architectures by implementing HAL traits only |
| PIE + KASLR | Linker scripts, relocation engine | Position-independent binaries with address randomization |
Helix's architecture ensures you never need to touch another crate's internals. Everything goes through traits and registries. Want a custom scheduler? Implement
Scheduler. Custom filesystem? ImplementFileSystemOps. The framework handles the rest.