# serenityos/serenity architecture

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

- Interactive diagram: https://gitdiagram.com/serenityos/serenity
- Repository: https://github.com/serenityos/serenity

## Overview

SerenityOS is a graphical Unix-like operating system. Its principal user workflow is interacting with GUI applications, including the browser, which relies on userland libraries and OS services; system calls then connect userland to the kernel and hardware. The README documents broader networking, filesystems, security, and desktop capabilities, while the sampled source gives detail only for selected web, storage, and kernel-device components. Accordingly, broader subsystem links are shown only where documented; unsampled internal wiring is omitted.

Main entry points: [`Userland/Libraries/LibWeb`](https://github.com/serenityos/serenity/tree/master/Userland/Libraries/LibWeb) (Web engine), [`Userland/Applications/Browser`](https://github.com/serenityos/serenity/tree/master/Userland/Applications/Browser) (Browser), [`Kernel`](https://github.com/serenityos/serenity/tree/master/Kernel) (Kernel core), [`Userland/Applications`](https://github.com/serenityos/serenity/tree/master/Userland/Applications) (GUI applications)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_platform["Kernel platform"]
  node_kernel_api["Kernel API"]
  node_kernel["Kernel core"]
  node_architecture["CPU architectures"]
  node_devices["Device drivers"]
  node_storage_controller["Storage controller"]
end

subgraph group_userland["Userland system"]
  node_applications["GUI applications"]
  node_browser["Browser"]
  node_services["System services"]
  node_libc["POSIX interface"]
end

subgraph group_web["Web runtime"]
  node_libweb["Web engine"]
  node_selector["CSS selector engine<br/>[SelectorEngine.cpp]"]
  node_dragdrop["Drag and drop"]
  node_storage_api["Web storage API<br/>[StorageManager.cpp]"]
end

subgraph group_shared["Shared libraries"]
  node_search_engines["Search engine choices<br/>[SearchEngine.cpp]"]
  node_ak["AK utilities"]
end

node_user(("Computer user"))
node_hardware(("Computer hardware"))
node_network(("Network services"))

node_user -->|"uses"| node_applications
node_user -->|"browses"| node_browser
node_applications -->|"uses"| node_services
node_applications -->|"uses"| node_libc
node_browser -->|"uses"| node_libweb
node_browser -->|"offers search"| node_search_engines
node_libweb -->|"matches selectors"| node_selector
node_libweb -->|"handles drags"| node_dragdrop
node_libweb -->|"exposes API"| node_storage_api
node_network -->|"serves content"| node_browser
node_libc -->|"invokes syscalls"| node_kernel_api
node_kernel_api -->|"dispatches"| node_kernel
node_kernel -->|"uses CPU support"| node_architecture
node_kernel -->|"manages devices"| node_devices
node_devices -->|"implements storage"| node_storage_controller
node_storage_controller -->|"controls storage"| node_hardware
node_libweb -->|"uses utilities"| node_ak

click node_applications "https://github.com/serenityos/serenity/tree/master/Userland/Applications"
click node_browser "https://github.com/serenityos/serenity/tree/master/Userland/Applications/Browser"
click node_services "https://github.com/serenityos/serenity/tree/master/Userland/Services"
click node_libc "https://github.com/serenityos/serenity/tree/master/Userland/Libraries/LibC"
click node_kernel_api "https://github.com/serenityos/serenity/tree/master/Kernel/API"
click node_kernel "https://github.com/serenityos/serenity/tree/master/Kernel"
click node_architecture "https://github.com/serenityos/serenity/tree/master/Kernel/Arch"
click node_devices "https://github.com/serenityos/serenity/tree/master/Kernel/Devices"
click node_storage_controller "https://github.com/serenityos/serenity/blob/master/Kernel/Devices/Storage/StorageController.h"
click node_libweb "https://github.com/serenityos/serenity/tree/master/Userland/Libraries/LibWeb"
click node_selector "https://github.com/serenityos/serenity/blob/master/Userland/Libraries/LibWeb/CSS/SelectorEngine.cpp"
click node_dragdrop "https://github.com/serenityos/serenity/blob/master/Userland/Libraries/LibWeb/Page/DragAndDropEventHandler.cpp"
click node_storage_api "https://github.com/serenityos/serenity/blob/master/Userland/Libraries/LibWeb/StorageAPI/StorageManager.cpp"
click node_search_engines "https://github.com/serenityos/serenity/blob/master/Userland/Libraries/LibWebView/SearchEngine.cpp"
click node_ak "https://github.com/serenityos/serenity/tree/master/AK"

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_api,node_kernel,node_architecture,node_devices,node_storage_controller,node_user toneBlue
class node_applications,node_browser,node_services,node_libc toneAmber
class node_libweb,node_selector,node_dragdrop,node_storage_api toneMint
class node_search_engines,node_ak toneRose
class node_hardware,node_network toneIndigo
```

## Components

### Kernel platform

- [Kernel API](https://github.com/serenityos/serenity/tree/master/Kernel/API): `Kernel/API`
- [Kernel core](https://github.com/serenityos/serenity/tree/master/Kernel): `Kernel`
- [CPU architectures](https://github.com/serenityos/serenity/tree/master/Kernel/Arch): `Kernel/Arch`
- [Device drivers](https://github.com/serenityos/serenity/tree/master/Kernel/Devices): `Kernel/Devices`
- [Storage controller](https://github.com/serenityos/serenity/blob/master/Kernel/Devices/Storage/StorageController.h): `Kernel/Devices/Storage/StorageController.h`

### Userland system

- [GUI applications](https://github.com/serenityos/serenity/tree/master/Userland/Applications): `Userland/Applications`
- [Browser](https://github.com/serenityos/serenity/tree/master/Userland/Applications/Browser): `Userland/Applications/Browser`
- [System services](https://github.com/serenityos/serenity/tree/master/Userland/Services): `Userland/Services`
- [POSIX interface](https://github.com/serenityos/serenity/tree/master/Userland/Libraries/LibC): `Userland/Libraries/LibC`

### Web runtime

- [Web engine](https://github.com/serenityos/serenity/tree/master/Userland/Libraries/LibWeb): `Userland/Libraries/LibWeb`
- [CSS selector engine](https://github.com/serenityos/serenity/blob/master/Userland/Libraries/LibWeb/CSS/SelectorEngine.cpp): `Userland/Libraries/LibWeb/CSS/SelectorEngine.cpp`
- [Drag and drop](https://github.com/serenityos/serenity/blob/master/Userland/Libraries/LibWeb/Page/DragAndDropEventHandler.cpp): `Userland/Libraries/LibWeb/Page/DragAndDropEventHandler.cpp`
- [Web storage API](https://github.com/serenityos/serenity/blob/master/Userland/Libraries/LibWeb/StorageAPI/StorageManager.cpp): `Userland/Libraries/LibWeb/StorageAPI/StorageManager.cpp`

### Shared libraries

- [Search engine choices](https://github.com/serenityos/serenity/blob/master/Userland/Libraries/LibWebView/SearchEngine.cpp): `Userland/Libraries/LibWebView/SearchEngine.cpp`
- [AK utilities](https://github.com/serenityos/serenity/tree/master/AK): `AK`

### Other components

- **Computer user**
- **Computer hardware**
- **Network services**

## Connections

- Computer user → GUI applications: uses
- Computer user → Browser: browses
- GUI applications → System services: uses
- GUI applications → POSIX interface: uses
- Browser → Web engine: uses
- Browser → Search engine choices: offers search
- Web engine → CSS selector engine: matches selectors
- Web engine → Drag and drop: handles drags
- Web engine → Web storage API: exposes API
- Network services → Browser: serves content
- POSIX interface → Kernel API: invokes syscalls
- Kernel API → Kernel core: dispatches
- Kernel core → CPU architectures: uses CPU support
- Kernel core → Device drivers: manages devices
- Device drivers → Storage controller: implements storage
- Storage controller → Computer hardware: controls storage
- Web engine → AK utilities: uses utilities