# petitstrawberry/scarlet architecture

> Architecture diagram of the GitHub repository petitstrawberry/scarlet, 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/petitstrawberry/scarlet
- Repository: https://github.com/petitstrawberry/scarlet

## Overview

1. **Repository shape**
   This is a monorepo for an operating-system stack, not just a kernel. The top-level split is: `kernel/` for the OS core, `user/` for userspace libraries and programs, `drivers/` for reusable device-driver crates, `modules/` for loadable kernel modules, `bundles/` and `projects/` for bootable image definitions, and `tools/` / `scripts/` for build and deployment automation.

2. **Boot and system image boundary**
   Scarlet boots through the **Limine** boot protocol on both **AArch64** and **RISC-V 64**. The `projects/*` and `bundles/*` trees define the bootable layouts: kernel + initramfs/rootfs + system configuration + userspace binaries. The `kernel/lds/` and project-specific linker scripts control final image layout, while `docs/boot/` and `docs/architecture/` describe the target boot and memory model.

3. **Kernel core responsibilities**
   The `kernel/` crate is the central runtime. It contains task scheduling, memory management, VFS, IPC, networking, syscalls, signal/process handling, and device management. This kernel is designed to host multiple ABIs natively and to expose the same underlying kernel objects to all of them.

4. **Multi-ABI execution model**
   A key architectural boundary is the ABI layer under `kernel/src/abi/`. Scarlet native, xv6, and partial Linux support are implemented as separate ABI modules, but they share common kernel subsystems such as VFS, task objects, pipes, sockets, and memory mappings. The kernel selects behavior based on the binary format / ABI being launched, which is what enables cross-ABI piping and container-like coexistence.

5. **Architecture-specific execution paths**
   `kernel/src/arch/aarch64/` and `kernel/src/arch/riscv64/` hold CPU-specific boot, trap, interrupt, timer, MMU, FPU, and context-switch logic. These platform layers adapt the shared kernel to the actual machine. The repo also includes architecture-specific targets under `kernel/targets/` and `user/targets/`, indicating separate build outputs for kernel and userspace.

6. **Device model and driver split**
   The kernel has an internal device abstraction layer under `kernel/src/device/`, while reusable low-level driver implementations live under `kernel/src/drivers/` and the standalone `drivers/` workspace crates. This separation lets the kernel talk to generic devices like block, char, graphics, input, network, USB, PCI, and power while arch- or platform-specific drivers bind to actual hardware or virtio devices.

7. **Filesystem and container isolation**
   VFS v2 is a major subsystem (`kernel/src/fs/vfs_v2/`) with drivers for `tmpfs`, `cpiofs`, `devfs`, `devpts`, `ext2`, `fat32`, `overlayfs`, and `initramfs`. The filesystem layer is tied to container isolation through mount namespaces, bind mounts, and overlay behavior. In practice, this is where rootfs images, initramfs content, and per-task filesystem views converge.

8. **Task, object, and IPC layer**
   Process-like execution is managed by `kernel/src/task/` and `kernel/src/sched/`, while `kernel/src/object/` provides capability-oriented handles for files, sockets, memory mappings, selectable objects, streams, and introspection. IPC is a first-class subsystem (`pipe`, `event`, `shared_memory`, `counter`), and user-space programs depend on these shared kernel objects for composition across ABI boundaries.

9. **Networking stack**
   The kernel includes a full protocol stack under `kernel/src/network/` with Ethernet, ARP, IPv4, ICMP, UDP, TCP, local sockets, and syscall bindings. Driver integration is primarily through virtio networking and the common socket/file abstractions, which makes networking part of the same cross-ABI resource model as files and pipes.

10. **Graphics, input, and desktop pipeline**
   Graphics support flows from device drivers into the kernel graphics manager and framebuffer/display abstractions, then out to userspace windowing services. The desktop stack is split across `user/bin/src/sws*`, `user/bin/src/sas*`, `user/bin/src/stemd/desktop.rs`, and client libraries under `user/lib/sws-client` and `user/lib/slint-scarlet`. This forms the window compositor, input routing, and UI protocol boundary.

11. **Userspace platform libraries and apps**
   `user/lib/` contains the runtime and system libraries used by applications: Scarlet OS FFI and handles, syscalls, sockets, IPC, polling, time, hypervisor support, GUI/windowing clients, and package management. `user/bin/` contains the actual executables and services: shell, login, networking tools, desktop components, compositor, resolver, package manager, and various demo/test programs. These binaries are the main consumers of the kernel ABI surface.

12. **Service management and system initialization**
   System startup is coordinated by `stemd` and service definitions in `bundles/*/fs/system/scarlet/etc/stemd.d/` and corresponding userspace implementations in `user/bin/src/stemd/`. Services include networking configuration, login, resolver, desktop compositor, and input/bridge services. The architecture resembles a small service graph rather than a single monolithic init process.

13. **Hypervisor and guest support**
   Scarlet also contains an experimental built-in hypervisor under `kernel/src/hypervisor/` and architecture-specific virtual-machine support in `kernel/src/arch/*/hv/`. The `guest_tests/` directory and `user/bin/src/ushv/` show the guest-facing and device-model side of this subsystem. This is a distinct boundary from normal process execution: the kernel can run guests with separate virtual CPUs, memory, and device emulation.

14. **Build, packaging, and deployment**
   The repo is built as a reproducible system with **Nix flakes**, `cargo-make`, and Docker support, while `projects/` and `bundles/` define concrete runtime images. `tools/` holds image-building, guest-image, and deployment scripts; `test-pkg/` and `tools/scpm-pack/` support package creation; and CI workflows in `.github/workflows/` automate build, test, and deployment. For an architecture diagram, these are the outer orchestration layers feeding the kernel/userspace images.

Main entry points: [`kernel`](https://github.com/petitstrawberry/scarlet/tree/dev/kernel) (Kernel core), [`kernel/src/abi`](https://github.com/petitstrawberry/scarlet/tree/dev/kernel/src/abi) (ABI layer), [`bundles`](https://github.com/petitstrawberry/scarlet/tree/dev/bundles) (Boot images), [`docs/architecture`](https://github.com/petitstrawberry/scarlet/tree/dev/docs/architecture) (Architecture docs)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_core["Kernel core"]
  node_kernel_core["Kernel core<br/>OS runtime"]
  node_boot_arch["Boot & arch<br/>platform layer"]
  node_abi_layer["ABI layer<br/>multi-ABI dispatch"]
  node_mem_subsystem["Memory<br/>allocator/vmem"]
  node_task_sched["Tasks & sched<br/>execution"]
  node_vfs["VFS v2<br/>filesystem core"]
  node_objects_ipc["Objects & IPC<br/>kernel objects"]
  node_network_stack["Networking<br/>protocol stack"]
  node_device_model["Device model<br/>device abstraction"]
  node_kernel_drivers["Kernel drivers"]
  node_hypervisor["Hypervisor<br/>guest runtime"]
end

subgraph group_user["Userspace"]
  node_userspace_rt["Runtime libs<br/>userspace foundation"]
  node_user_bins["User programs<br/>services/apps"]
  node_std_apps["Std binaries<br/>core utils"]
  node_desktop_stack["Desktop stack<br/>windowing UI"]
  node_system_init["System init<br/>service graph"]
end

subgraph group_packaging["Images & build"]
  node_boot_images["Boot images<br/>bundle/project layouts"]
  node_project_layouts["Project layouts<br/>project BSPs"]
  node_tooling["Build tools<br/>automation"]
end

subgraph group_drivers["Reusable drivers"]
  node_driver_crates["Driver crates<br/>workspace drivers"]
end

subgraph group_modules["Loadable modules"]
  node_loadable_modules["Loadable modules<br/>kernel modules"]
end

subgraph group_docs["Docs"]
  node_architecture_docs["Architecture docs<br/>design docs"]
end

node_boot_images -->|"bundle kernel"| node_kernel_core
node_project_layouts -->|"define layouts"| node_boot_images
node_tooling -->|"build/deploy"| node_boot_images
node_tooling -->|"run targets"| node_project_layouts
node_kernel_core -->|"uses"| node_boot_arch
node_kernel_core -->|"dispatches"| node_abi_layer
node_kernel_core -->|"manages"| node_mem_subsystem
node_kernel_core -->|"schedules"| node_task_sched
node_kernel_core -->|"mounts"| node_vfs
node_kernel_core -->|"exposes"| node_objects_ipc
node_kernel_core -->|"serves"| node_network_stack
node_kernel_core -->|"binds devices"| node_device_model
node_kernel_core -->|"loads drivers"| node_kernel_drivers
node_kernel_core -->|"hosts guests"| node_hypervisor
node_abi_layer -->|"shares"| node_vfs
node_abi_layer -->|"shares"| node_objects_ipc
node_abi_layer -->|"reuses"| node_task_sched
node_device_model -->|"integrates"| node_driver_crates
node_boot_arch -->|"platform support"| node_driver_crates
node_userspace_rt -->|"syscalls"| node_kernel_core
node_user_bins -->|"link against"| node_userspace_rt
node_std_apps -->|"link against"| node_userspace_rt
node_desktop_stack -->|"renders/input"| node_device_model
node_system_init -->|"starts"| node_user_bins
node_loadable_modules -->|"extends"| node_kernel_core
node_architecture_docs -.->|"describes"| node_kernel_core
node_architecture_docs -.->|"describes"| node_boot_images
node_architecture_docs -.->|"describes"| node_desktop_stack

click node_boot_images "https://github.com/petitstrawberry/scarlet/tree/dev/bundles"
click node_project_layouts "https://github.com/petitstrawberry/scarlet/tree/dev/projects"
click node_tooling "https://github.com/petitstrawberry/scarlet/tree/dev/tools"
click node_kernel_core "https://github.com/petitstrawberry/scarlet/tree/dev/kernel"
click node_boot_arch "https://github.com/petitstrawberry/scarlet/tree/dev/kernel/src/arch"
click node_abi_layer "https://github.com/petitstrawberry/scarlet/tree/dev/kernel/src/abi"
click node_mem_subsystem "https://github.com/petitstrawberry/scarlet/tree/dev/kernel/src/mem"
click node_task_sched "https://github.com/petitstrawberry/scarlet/tree/dev/kernel/src/task"
click node_vfs "https://github.com/petitstrawberry/scarlet/tree/dev/kernel/src/fs/vfs_v2"
click node_objects_ipc "https://github.com/petitstrawberry/scarlet/tree/dev/kernel/src/object"
click node_network_stack "https://github.com/petitstrawberry/scarlet/tree/dev/kernel/src/network"
click node_device_model "https://github.com/petitstrawberry/scarlet/tree/dev/kernel/src/device"
click node_kernel_drivers "https://github.com/petitstrawberry/scarlet/tree/dev/kernel/src/drivers"
click node_hypervisor "https://github.com/petitstrawberry/scarlet/tree/dev/kernel/src/hypervisor"
click node_userspace_rt "https://github.com/petitstrawberry/scarlet/tree/dev/user/lib"
click node_user_bins "https://github.com/petitstrawberry/scarlet/tree/dev/user/bin"
click node_std_apps "https://github.com/petitstrawberry/scarlet/tree/dev/user/std-bin"
click node_desktop_stack "https://github.com/petitstrawberry/scarlet/tree/dev/user/bin/src/sws"
click node_system_init "https://github.com/petitstrawberry/scarlet/tree/dev/user/bin/src/stemd"
click node_driver_crates "https://github.com/petitstrawberry/scarlet/tree/dev/drivers"
click node_loadable_modules "https://github.com/petitstrawberry/scarlet/tree/dev/modules/loadable"
click node_architecture_docs "https://github.com/petitstrawberry/scarlet/tree/dev/docs/architecture"

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_kernel_core,node_boot_arch,node_abi_layer,node_mem_subsystem,node_task_sched,node_vfs,node_objects_ipc,node_network_stack,node_device_model,node_kernel_drivers,node_hypervisor toneBlue
class node_userspace_rt,node_user_bins,node_std_apps,node_desktop_stack,node_system_init toneAmber
class node_boot_images,node_project_layouts,node_tooling toneMint
class node_driver_crates toneRose
class node_loadable_modules toneIndigo
class node_architecture_docs toneTeal
```

## Components

### Kernel core

Shared OS runtime and execution model.

- [Kernel core](https://github.com/petitstrawberry/scarlet/tree/dev/kernel): OS runtime · Central kernel crate providing process, memory, VFS, IPC, networking, and syscalls. · `kernel`
- [Boot & arch](https://github.com/petitstrawberry/scarlet/tree/dev/kernel/src/arch): platform layer · Boot entry, CPU setup, traps, interrupts, timers, MMU, and context switching for AArch64 and RISC-V. · `kernel/src/arch`
- [ABI layer](https://github.com/petitstrawberry/scarlet/tree/dev/kernel/src/abi): multi-ABI dispatch · Scarlet, xv6, and partial Linux execution paths sharing the same kernel objects. · `kernel/src/abi`
- [Memory](https://github.com/petitstrawberry/scarlet/tree/dev/kernel/src/mem): allocator/vmem · Physical and virtual memory management, paging, boot mappings, and ioremap. · `kernel/src/mem`
- [Tasks & sched](https://github.com/petitstrawberry/scarlet/tree/dev/kernel/src/task): execution · Task lifecycle, namespaces, and scheduler coordination. · `kernel/src/task`
- [VFS v2](https://github.com/petitstrawberry/scarlet/tree/dev/kernel/src/fs/vfs_v2): filesystem core · Unified filesystem and mount layer with overlay, tmpfs, initramfs, ext2, fat32, devfs, and devpts. · `kernel/src/fs/vfs_v2`
- [Objects & IPC](https://github.com/petitstrawberry/scarlet/tree/dev/kernel/src/object): kernel objects · Capability-style handles, memory mappings, pipes, events, counters, and shared memory. · `kernel/src/object`
- [Networking](https://github.com/petitstrawberry/scarlet/tree/dev/kernel/src/network): protocol stack · Ethernet, ARP, IPv4, ICMP, UDP, TCP, local sockets, and syscall bindings. · `kernel/src/network`
- [Device model](https://github.com/petitstrawberry/scarlet/tree/dev/kernel/src/device): device abstraction · Kernel-facing device manager and generic device classes for block, char, input, graphics, network, USB, PCI, and power. · `kernel/src/device`
- [Kernel drivers](https://github.com/petitstrawberry/scarlet/tree/dev/kernel/src/drivers): in-kernel drivers · Built-in drivers for virtio, graphics, UART, USB, PCI, RTC, and timers. · `kernel/src/drivers`
- [Hypervisor](https://github.com/petitstrawberry/scarlet/tree/dev/kernel/src/hypervisor): guest runtime · Built-in VM, vCPU, trap, and device-model support for guest execution. · `kernel/src/hypervisor`

### Userspace

Libraries, services, and applications.

- [Runtime libs](https://github.com/petitstrawberry/scarlet/tree/dev/user/lib): userspace foundation · Scarlet ABI, runtime, syscalls, handles, IPC, sockets, polling, time, and GUI client libraries. · `user/lib`
- [User programs](https://github.com/petitstrawberry/scarlet/tree/dev/user/bin): services/apps · Shell, login, network tools, desktop components, package manager, demos, and system services. · `user/bin`
- [Std binaries](https://github.com/petitstrawberry/scarlet/tree/dev/user/std-bin): core utils · Standalone utility programs and small service binaries built against the userspace standard library. · `user/std-bin`
- [Desktop stack](https://github.com/petitstrawberry/scarlet/tree/dev/user/bin/src/sws): windowing UI · SWS compositor, SAS input/service path, desktop shell, and GUI client libraries. · `user/bin/src/sws`
- [System init](https://github.com/petitstrawberry/scarlet/tree/dev/user/bin/src/stemd): service graph · stemd and service definitions used to start login, networking, resolver, and desktop services. · `user/bin/src/stemd`

### Images & build

Bootable layouts and orchestration.

- [Boot images](https://github.com/petitstrawberry/scarlet/tree/dev/bundles): bundle/project layouts · Bootable system definitions combining kernel, rootfs/initramfs, config, and userspace. · `bundles`
- [Project layouts](https://github.com/petitstrawberry/scarlet/tree/dev/projects): project BSPs · Per-target image definitions and linker scripts for Limine boot and final layout. · `projects`
- [Build tools](https://github.com/petitstrawberry/scarlet/tree/dev/tools): automation · Scripts and tools for image building, deployment, guest images, and packaging. · `tools`

### Reusable drivers

Standalone hardware driver crates.

- [Driver crates](https://github.com/petitstrawberry/scarlet/tree/dev/drivers): workspace drivers · Reusable low-level driver crates outside the kernel workspace, especially Apple platform components. · `drivers`

### Loadable modules

Kernel module experiments and tests.

- [Loadable modules](https://github.com/petitstrawberry/scarlet/tree/dev/modules/loadable): kernel modules · Experimental and testable loadable modules for the kernel module interface. · `modules/loadable`

### Docs

Architecture and subsystem design notes.

- [Architecture docs](https://github.com/petitstrawberry/scarlet/tree/dev/docs/architecture): design docs · Boot, architecture, container, network, hypervisor, graphics, services, and module design notes. · `docs/architecture`

## Connections

- Boot images → Kernel core: bundle kernel · Bootable images package the central kernel runtime.
- Project layouts → Boot images: define layouts · Project BSPs and linker scripts assemble concrete images.
- Build tools → Boot images: build/deploy · Automation produces system images and deployment artifacts.
- Build tools → Project layouts: run targets · Scripts launch project-specific boot and test flows.
- Kernel core → Boot & arch: uses · The kernel depends on architecture-specific boot and execution paths.
- Kernel core → ABI layer: dispatches · Binary format and ABI determine syscall and process behavior.
- Kernel core → Memory: manages · Kernel memory management underpins mappings and allocation.
- Kernel core → Tasks & sched: schedules · Task and scheduler subsystems drive execution.
- Kernel core → VFS v2: mounts · Filesystem operations converge in VFS v2.
- Kernel core → Objects & IPC: exposes · Kernel objects and IPC are the shared composition boundary.
- Kernel core → Networking: serves · Sockets and network syscalls sit on the kernel stack.
- Kernel core → Device model: binds devices · The kernel mediates hardware through its device abstraction.
- Kernel core → Kernel drivers: loads drivers · Built-in drivers connect the kernel to platforms and virtio.
- Kernel core → Hypervisor: hosts guests · Guest execution is implemented as a distinct kernel subsystem.
- ABI layer → VFS v2: shares · ABIs reuse the same filesystem and mount objects.
- ABI layer → Objects & IPC: shares · ABIs share handles, pipes, sockets, and mappings.
- ABI layer → Tasks & sched: reuses · ABI-specific process behavior runs on the common task model.
- Device model → Driver crates: integrates · Generic device classes connect to reusable driver crates.
- Boot & arch → Driver crates: platform support · Architecture layers depend on low-level platform drivers.
- Runtime libs → Kernel core: syscalls · Userspace libraries are the primary consumers of the kernel ABI.
- User programs → Runtime libs: link against · Applications and services use the userspace runtime libraries.
- Std binaries → Runtime libs: link against · Utility binaries share the same userspace foundations.
- Desktop stack → Device model: renders/input · Desktop components sit on top of graphics and input device abstractions.
- System init → User programs: starts · stemd launches and coordinates service binaries.
- Loadable modules → Kernel core: extends · Modules attach to kernel internals through the module interface.
- Architecture docs → Kernel core: describes · Docs explain the core kernel architecture and boundaries.
- Architecture docs → Boot images: describes · Docs explain the boot and image model.
- Architecture docs → Desktop stack: describes · Docs explain the graphics and desktop pipeline.