# klange/toaruos architecture

> Architecture diagram of the GitHub repository klange/toaruos, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-23). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/klange/toaruos
- Repository: https://github.com/klange/toaruos

## Overview

1. **Overall shape**
   - This repository is the full source tree for ToaruOS: bootloader, kernel, C library, userland libraries, applications, system configuration, and packaging/build tooling.
   - It is a self-contained OS rather than an app stack on top of another host OS.

2. **Boot path**
   - `boot/` contains the BIOS/EFI loader and menus that select kernel options, load the kernel, and pass the initial ramdisk and boot arguments.
   - The bootloader’s job ends once control transfers to the kernel entry points for either `x86_64` or `aarch64`.

3. **Kernel core**
   - `kernel/` is the central runtime: process management, memory management, syscall dispatch, VFS, networking, device abstractions, and architecture-specific startup code.
   - Architecture code is split under `kernel/arch/x86_64` and `kernel/arch/aarch64`, with separate boot, interrupt, MMU, SMP, and platform support.

4. **Kernel subsystems**
   - Major in-kernel boundaries are `sys/` for process/syscall-facing services, `vfs/` for filesystem and device-file plumbing, `net/` for Ethernet/IP/socket stack, `video/` for framebuffer graphics, and `audio/` for sound.
   - The kernel also hosts loadable drivers in `modules/`, which plug into hardware support such as storage, network, USB, audio, and filesystems.

5. **Device and filesystem model**
   - User-visible state is exposed through virtual filesystems like `/proc`, `/dev`, and pseudo-devices for terminals, pipes, random, and packet exchange.
   - Real storage enters through filesystem drivers such as ext2, ISO9660, ramdisk, tmpfs, and tarfs, while runtime configuration and package state live in the staged root filesystem under `base/`.

6. **Userspace ABI boundary**
   - `libc/` provides the C runtime, system call wrappers, startup objects, dynamic loader (`dlfcn`), pthreads, stdio, math, locale, and other POSIX-ish interfaces.
   - This is the key boundary between applications and the kernel: most programs link against `libc` and talk to the kernel only through syscalls and device files.

7. **Shared userland libraries**
   - `lib/` contains higher-level first-party libraries for graphics, widgets, menus, text rendering, compression/image parsing, procfs helpers, line editing, and IPC/windowing support.
   - These libraries are used by both CLI and GUI apps, especially anything that draws windows or interacts with the desktop session.

8. **Desktop/windowing stack**
   - The graphical desktop is centered on `apps/compositor.c`, which is the Yutani compositor/window server.
   - Yutani manages window buffers, layout, cursor/input routing, and compositor-side presentation, while clients use `lib/yutani.c` and related libraries to create and update windows.

9. **Session and login flow**
   - System startup scripts in `base/etc/startup.d/` bring up hostname, tmpfs, modules, networking, and then launch the interactive session.
   - Login/session programs in `apps/` handle console or graphical entry points, and the default desktop/session environment is assembled from the staged home directories and launcher files under `base/home/local/Desktop`.

10. **Applications and utilities**
    - `apps/` is the first-party userland collection: shell, terminal, file browser, package manager, system tools, games, graphics utilities, and many Unix-like command-line tools.
    - Several applications are graphical and depend on Yutani; others are terminal utilities that primarily exercise libc, VFS, procfs, and device files.

11. **Scripting and extensibility**
    - Kuroko is used as an embedded dynamic language for various tools and demos, with `.krk` applications and library integrations under `lib/kuroko/`.
    - Some “applications” are shell scripts or Kuroko scripts in `apps/` and `base/etc/startup.d/`, showing that the runtime supports mixed executable types.

12. **Filesystem staging and runtime image**
    - `base/` is not the live OS itself but the staging root used to assemble the bootable image.
    - It provides the directory skeleton, config files, default user homes, shared resources, headers, and manpages that are packaged into the ramdisk and ISO image.

13. **Build and packaging pipeline**
    - The top-level `Makefile` and `build/` scripts orchestrate cross-compilation for x86-64 and aarch64, generate dependency metadata, build kernel/libc/libs/apps, and assemble the bootable image.
    - `util/` contains toolchain, image, and disk-generation helpers; the output path is a ramdisk plus ISO9660 boot image rather than a conventional package repository.

14. **Testing and validation**
    - `tests/` contains kernel/userspace validation programs for syscalls, libc behavior, threading, signals, networking, and graphics-related edge cases.
    - The GitHub Actions workflows under `.github/workflows/` indicate CI builds for both supported architectures, which matters because architecture-specific code paths are substantial.

15. **External dependencies and deployment targets**
    - The project is designed to boot on real hardware, QEMU, and virtualization platforms like VirtualBox/VMware; some drivers and boot behaviors are tuned for those environments.
    - Hardware support is mediated through kernel modules and architecture-specific code, while runtime services like networking, display sizing, and absolute mouse support are exposed through the OS’s own drivers and desktop stack.

Main entry points: [`kernel/generic.c`](https://github.com/klange/toaruos/blob/master/kernel/generic.c) (Kernel core), [`Makefile`](https://github.com/klange/toaruos/tree/master/Makefile) (Build system), [`libc`](https://github.com/klange/toaruos/tree/master/libc) (libc), [`modules`](https://github.com/klange/toaruos/tree/master/modules) (Modules)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_group_boot["Boot path"]
  node_bootloader["Bootloader<br/>loader/menus"]
end

subgraph group_group_kernel["Kernel"]
  node_kernel_core["Kernel core<br/>os kernel<br/>[generic.c]"]
  node_kernel_arch_x86["x86_64 arch<br/>arch port"]
  node_kernel_arch_aarch64["aarch64 arch<br/>arch port"]
  node_kernel_sys["Syscalls<br/>process/syscall"]
  node_kernel_vfs["VFS<br/>filesystem core"]
  node_kernel_net["Network"]
  node_kernel_video["Video<br/>display driver"]
  node_kernel_audio["Audio<br/>sound driver"]
  node_kernel_modules["Modules<br/>loadable drivers"]
end

subgraph group_group_userland["Userland"]
  node_libc["libc<br/>userspace ABI"]
  node_shared_libs["Shared libs<br/>first-party libs"]
  node_compositor["Compositor<br/>window server<br/>[compositor.c]"]
  node_login_session["Login & session<br/>session startup<br/>[init.c]"]
  node_apps["Applications<br/>userland tools"]
  node_scripts["Scripts<br/>shell/krk apps<br/>[startup.d]"]
end

subgraph group_group_image["Image & build"]
  node_base_root[("Staging root<br/>image rootfs")]
  node_build_pipeline["Build system<br/>build/tooling"]
  node_util_tools["Image tools<br/>packaging helpers"]
end

node_tests["Tests<br/>validation suite"]

node_bootloader -->|"boot handoff"| node_kernel_core
node_kernel_core -->|"x86_64 runtime"| node_kernel_arch_x86
node_kernel_core -->|"aarch64 runtime"| node_kernel_arch_aarch64
node_kernel_core -->|"syscall path"| node_kernel_sys
node_kernel_core -->|"vfs path"| node_kernel_vfs
node_kernel_core -->|"network path"| node_kernel_net
node_kernel_core -->|"display path"| node_kernel_video
node_kernel_core -->|"audio path"| node_kernel_audio
node_kernel_core -->|"driver API"| node_kernel_modules
node_kernel_modules -->|"storage fs"| node_kernel_vfs
node_kernel_modules -->|"net hw"| node_kernel_net
node_kernel_modules -->|"sound hw"| node_kernel_audio
node_libc -->|"syscalls"| node_kernel_sys
node_libc -->|"files/devices"| node_kernel_vfs
node_shared_libs -->|"built on"| node_libc
node_shared_libs -->|"windowing"| node_compositor
node_compositor -->|"presentation"| node_kernel_video
node_compositor -->|"input/events"| node_kernel_sys
node_login_session -->|"desktop start"| node_compositor
node_login_session -->|"launches"| node_apps
node_scripts -->|"startup flow"| node_login_session
node_base_root -->|"staged config"| node_scripts
node_build_pipeline -->|"assembles"| node_base_root
node_build_pipeline -->|"builds"| node_bootloader
node_build_pipeline -->|"builds"| node_kernel_core
node_build_pipeline -->|"builds"| node_libc
node_build_pipeline -->|"builds"| node_apps
node_util_tools -->|"supports"| node_build_pipeline
node_tests -->|"validates"| node_libc
node_tests -->|"validates"| node_kernel_sys
node_tests -->|"validates"| node_kernel_net

click node_bootloader "https://github.com/klange/toaruos/tree/master/boot"
click node_kernel_core "https://github.com/klange/toaruos/blob/master/kernel/generic.c"
click node_kernel_arch_x86 "https://github.com/klange/toaruos/tree/master/kernel/arch/x86_64"
click node_kernel_arch_aarch64 "https://github.com/klange/toaruos/tree/master/kernel/arch/aarch64"
click node_kernel_sys "https://github.com/klange/toaruos/tree/master/kernel/sys"
click node_kernel_vfs "https://github.com/klange/toaruos/tree/master/kernel/vfs"
click node_kernel_net "https://github.com/klange/toaruos/tree/master/kernel/net"
click node_kernel_video "https://github.com/klange/toaruos/tree/master/kernel/video"
click node_kernel_audio "https://github.com/klange/toaruos/tree/master/kernel/audio"
click node_kernel_modules "https://github.com/klange/toaruos/tree/master/modules"
click node_libc "https://github.com/klange/toaruos/tree/master/libc"
click node_shared_libs "https://github.com/klange/toaruos/tree/master/lib"
click node_compositor "https://github.com/klange/toaruos/blob/master/apps/compositor.c"
click node_login_session "https://github.com/klange/toaruos/blob/master/apps/init.c"
click node_apps "https://github.com/klange/toaruos/tree/master/apps"
click node_scripts "https://github.com/klange/toaruos/blob/master/base/etc/startup.d"
click node_base_root "https://github.com/klange/toaruos/tree/master/base"
click node_build_pipeline "https://github.com/klange/toaruos/tree/master/Makefile"
click node_util_tools "https://github.com/klange/toaruos/tree/master/util"
click node_tests "https://github.com/klange/toaruos/tree/master/tests"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_bootloader toneBlue
class node_kernel_core,node_kernel_arch_x86,node_kernel_arch_aarch64,node_kernel_sys,node_kernel_vfs,node_kernel_net,node_kernel_video,node_kernel_audio,node_kernel_modules toneAmber
class node_libc,node_shared_libs,node_compositor,node_login_session,node_apps,node_scripts toneMint
class node_base_root,node_build_pipeline,node_util_tools toneRose
class node_tests toneNeutral
```

## Components

### Boot path

Firmware/loader code that transfers control into the OS kernel.

- [Bootloader](https://github.com/klange/toaruos/tree/master/boot): loader/menus · BIOS/EFI loading, kernel selection, boot arguments, and handoff to the kernel. · `boot`

### Kernel

Core privileged runtime, subsystems, and architecture-specific startup code.

- [Kernel core](https://github.com/klange/toaruos/blob/master/kernel/generic.c): os kernel · Central kernel runtime for processes, memory, syscalls, and global services. · `kernel/generic.c`
- [x86_64 arch](https://github.com/klange/toaruos/tree/master/kernel/arch/x86_64): arch port · x86_64 bootstrap, interrupts, MMU, SMP, and platform support. · `kernel/arch/x86_64`
- [aarch64 arch](https://github.com/klange/toaruos/tree/master/kernel/arch/aarch64): arch port · AArch64 bootstrap, interrupts, MMU, SMP, device tree, and board support. · `kernel/arch/aarch64`
- [Syscalls](https://github.com/klange/toaruos/tree/master/kernel/sys): process/syscall · Process management, signals, ptrace, shared memory, and syscall dispatch. · `kernel/sys`
- [VFS](https://github.com/klange/toaruos/tree/master/kernel/vfs): filesystem core · Virtual filesystem, pipes, terminals, procfs, ramdisk, tmpfs, and tarfs plumbing. · `kernel/vfs`
- [Network](https://github.com/klange/toaruos/tree/master/kernel/net): network stack · Ethernet, ARP, IPv4, loopback, and socket handling inside the kernel. · `kernel/net`
- [Video](https://github.com/klange/toaruos/tree/master/kernel/video): display driver · Framebuffer and low-level graphics output from the kernel. · `kernel/video`
- [Audio](https://github.com/klange/toaruos/tree/master/kernel/audio): sound driver · Kernel audio subsystem and sound device integration. · `kernel/audio`
- [Modules](https://github.com/klange/toaruos/tree/master/modules): loadable drivers · Hardware and filesystem drivers loaded into the kernel at runtime. · `modules`

### Userland

C library, shared libraries, applications, and session tooling.

- [libc](https://github.com/klange/toaruos/tree/master/libc): userspace ABI · C runtime, syscall wrappers, startup objects, dynamic loading, pthreads, and POSIX-ish APIs. · `libc`
- [Shared libs](https://github.com/klange/toaruos/tree/master/lib): first-party libs · Graphics, text, menus, procfs, line editing, IPC, compression, and widget support for apps. · `lib`
- [Compositor](https://github.com/klange/toaruos/blob/master/apps/compositor.c): window server · Yutani compositor and desktop presentation manager. · `apps/compositor.c`
- [Login & session](https://github.com/klange/toaruos/blob/master/apps/init.c): session startup · Console and graphical login, session launch, and startup coordination. · `apps/init.c`
- [Applications](https://github.com/klange/toaruos/tree/master/apps): userland tools · Shell, terminal, file tools, networking utilities, graphics apps, and games. · `apps`
- [Scripts](https://github.com/klange/toaruos/blob/master/base/etc/startup.d): shell/krk apps · Startup scripts and Kuroko-based tools used for setup, demos, and lightweight applications. · `base/etc/startup.d`

### Image & build

Staging root, packaging, and build pipeline for bootable images.

- [Staging root](https://github.com/klange/toaruos/tree/master/base): image rootfs · Packaged filesystem skeleton, configs, default homes, headers, manuals, and shared assets. · `base`
- [Build system](https://github.com/klange/toaruos/tree/master/Makefile): build/tooling · Top-level Makefile, per-architecture build rules, and image assembly tooling. · `Makefile`
- [Image tools](https://github.com/klange/toaruos/tree/master/util): packaging helpers · Toolchain, disk, ramdisk, and generation utilities for building bootable artifacts. · `util`

### Other components

- [Tests](https://github.com/klange/toaruos/tree/master/tests): validation suite · Kernel and userspace validation programs for syscalls, libc, threading, networking, and graphics edge cases. · `tests`

## Connections

- Bootloader → Kernel core: boot handoff · Loads the kernel and transfers control with boot parameters and init data.
- Kernel core → x86_64 arch: x86_64 runtime · Uses the x86_64 port for bootstrap, interrupts, and memory management.
- Kernel core → aarch64 arch: aarch64 runtime · Uses the AArch64 port for bootstrap, interrupts, and memory management.
- Kernel core → Syscalls: syscall path · Dispatches process and signal-related kernel services.
- Kernel core → VFS: vfs path · Routes file, device, and pseudo-filesystem operations through VFS.
- Kernel core → Network: network path · Provides socket and packet services through the network stack.
- Kernel core → Video: display path · Exposes framebuffer graphics support to userspace and drivers.
- Kernel core → Audio: audio path · Exposes kernel audio services and device integration.
- Kernel core → Modules: driver API · Loads and coordinates hardware/filesystem modules.
- Modules → VFS: storage fs · Ext2, ISO9660, ramdisk, tmpfs, and tarfs drivers plug into the VFS.
- Modules → Network: net hw · Network drivers feed packets and link status into the stack.
- Modules → Audio: sound hw · Audio drivers provide hardware-backed sound devices.
- libc → Syscalls: syscalls · Applications cross the ABI boundary through libc wrappers and startup code.
- libc → VFS: files/devices · Uses file descriptors, procfs, terminals, pipes, and device files.
- Shared libs → libc: built on · Shared libraries depend on the C runtime and syscall wrappers.
- Shared libs → Compositor: windowing · Graphics and Yutani support underpin the desktop/window server.
- Compositor → Video: presentation · Renders windows through kernel video services.
- Compositor → Syscalls: input/events · Consumes input and process services via the kernel ABI.
- Login & session → Compositor: desktop start · Starts the graphical session and desktop environment.
- Login & session → Applications: launches · Invokes shell, login, terminal, and session utilities.
- Scripts → Login & session: startup flow · Boot-time scripts prepare the session and then launch the user environment.
- Staging root → Scripts: staged config · Provides startup scripts, system config, and default user resources.
- Build system → Staging root: assembles · Packages the staged root filesystem into the bootable image.
- Build system → Bootloader: builds · Compiles boot-stage code and links boot artifacts.
- Build system → Kernel core: builds · Compiles the kernel and architecture-specific pieces.
- Build system → libc: builds · Builds the userspace ABI and runtime libraries.
- Build system → Applications: builds · Builds the first-party applications and utilities.
- Image tools → Build system: supports · Provides helper scripts for toolchains, image generation, and disk creation.
- Tests → libc: validates · Exercises libc behavior, threading, signals, and POSIX-like interfaces.
- Tests → Syscalls: validates · Covers syscall and kernel boundary behavior.
- Tests → Network: validates · Exercises networking edge cases.
