# kris-dreemurr-dev/overos architecture

> Architecture diagram of the GitHub repository kris-dreemurr-dev/overos, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-17). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/kris-dreemurr-dev/overos
- Repository: https://github.com/kris-dreemurr-dev/overos

## Overview

overOS is a bare-metal x86_64 operating system. Its documented startup proceeds from BIOS and the boot loader into kernel initialization, then starts terminal and user processes; users launch programs through the shell, while the desktop runs as a Ring 3 program. The map also preserves major documented capabilities: process isolation and scheduling, user permissions, USB storage and FAT32, desktop composition, built-in IDE/compiler, and game ports. Some subsystem links rely on README descriptions because their implementation files were not excerpted.

Main entry points: [`src/kernel/main.c`](https://github.com/kris-dreemurr-dev/overos/blob/main/src/kernel/main.c) (Kernel initialization), [`src/kernel/user_mode.c`](https://github.com/kris-dreemurr-dev/overos/blob/main/src/kernel/user_mode.c) (System call boundary), [`src/kernel/tty.h`](https://github.com/kris-dreemurr-dev/overos/blob/main/src/kernel/tty.h) (TTY and login), [`src/files/progs/Desktop/desktop.c`](https://github.com/kris-dreemurr-dev/overos/blob/main/src/files/progs/Desktop/desktop.c) (Desktop compositor)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_boot_kernel["Boot and kernel"]
  node_boot_menu["Boot and VBE menu<br/>[vbe_menu.c]"]
  node_kernel_init["Kernel initialization<br/>[main.c]"]
  node_memory["Physical and virtual memory<br/>[vmm.c]"]
end

subgraph group_process_user["Processes and users"]
  node_syscalls["System call boundary<br/>[user_mode.c]"]
  node_scheduler["Process scheduler<br/>[sched.c]"]
  node_user_permissions["Users and permissions<br/>[users.h]"]
  node_terminal_login["TTY and login<br/>[tty.h]"]
  node_shell["Ring 3 shell<br/>[sh.c]"]
end

subgraph group_device_storage["Devices and storage"]
  node_filesystem[("VFS and FAT32<br/>[fat32.c]")]
  node_block_registry["Block device registry<br/>[blk.h]"]
  node_usb_controllers["USB controllers<br/>[xhci.c]"]
  node_audio_driver["HDA audio<br/>[hda.c]"]
  node_network_driver["Ethernet<br/>[ethernet.c]"]
end

subgraph group_desktop_apps["Desktop and apps"]
  node_desktop["Desktop compositor<br/>[desktop.c]"]
  node_window_server["Window server<br/>[wserver.c]"]
  node_ui_library["UI library<br/>[ui.c]"]
  node_ide_compiler["IDE and C compiler<br/>[compiler.c]"]
end

subgraph group_game_ports["Game ports"]
  node_doom["DOOM port<br/>[d_main.c]"]
  node_quake["Quake port<br/>[host.c]"]
  node_overcraft["overCraft game<br/>[main.cpp]"]
  node_overcraft_engine["3D rendering engine<br/>[ovengine.h]"]
end

node_bios(("BIOS firmware"))
node_user(("Computer user"))

node_bios -->|"starts boot"| node_boot_menu
node_boot_menu -->|"loads kernel"| node_kernel_init
node_kernel_init -->|"initializes memory"| node_memory
node_kernel_init -->|"starts terminal"| node_terminal_login
node_kernel_init -->|"initializes scheduler"| node_scheduler
node_kernel_init -->|"initializes USB"| node_usb_controllers
node_kernel_init -->|"initializes storage"| node_filesystem
node_terminal_login -->|"loads accounts"| node_user_permissions
node_terminal_login -->|"starts shell"| node_shell
node_user -->|"enters commands"| node_shell
node_shell -->|"invokes services"| node_syscalls
node_syscalls -->|"controls processes"| node_scheduler
node_syscalls -->|"manages address spaces"| node_memory
node_syscalls -->|"performs file I/O"| node_filesystem
node_usb_controllers -->|"registers disks"| node_block_registry
node_block_registry -->|"serves sectors"| node_filesystem
node_user -->|"opens desktop"| node_desktop
node_desktop -->|"composes windows"| node_window_server
node_desktop -->|"uses widgets"| node_ui_library
node_user -->|"edits and builds"| node_ide_compiler
node_user -->|"plays"| node_doom
node_user -->|"plays"| node_quake
node_user -->|"plays"| node_overcraft
node_overcraft -->|"renders with"| node_overcraft_engine
node_kernel_init -->|"initializes audio"| node_audio_driver
node_kernel_init -->|"initializes network"| node_network_driver

click node_boot_menu "https://github.com/kris-dreemurr-dev/overos/blob/main/src/boot/vbe_menu.c"
click node_kernel_init "https://github.com/kris-dreemurr-dev/overos/blob/main/src/kernel/main.c"
click node_memory "https://github.com/kris-dreemurr-dev/overos/blob/main/src/memory/vmm.c"
click node_syscalls "https://github.com/kris-dreemurr-dev/overos/blob/main/src/kernel/user_mode.c"
click node_scheduler "https://github.com/kris-dreemurr-dev/overos/blob/main/src/kernel/sched.c"
click node_user_permissions "https://github.com/kris-dreemurr-dev/overos/blob/main/src/kernel/users.h"
click node_terminal_login "https://github.com/kris-dreemurr-dev/overos/blob/main/src/kernel/tty.h"
click node_shell "https://github.com/kris-dreemurr-dev/overos/blob/main/src/programs/sh.c"
click node_filesystem "https://github.com/kris-dreemurr-dev/overos/blob/main/src/fs/fat32.c"
click node_block_registry "https://github.com/kris-dreemurr-dev/overos/blob/main/src/drivers/blk.h"
click node_usb_controllers "https://github.com/kris-dreemurr-dev/overos/blob/main/src/drivers/usb/xhci.c"
click node_audio_driver "https://github.com/kris-dreemurr-dev/overos/blob/main/src/drivers/hda.c"
click node_network_driver "https://github.com/kris-dreemurr-dev/overos/blob/main/src/drivers/ethernet.c"
click node_desktop "https://github.com/kris-dreemurr-dev/overos/blob/main/src/files/progs/Desktop/desktop.c"
click node_window_server "https://github.com/kris-dreemurr-dev/overos/blob/main/src/files/progs/Desktop/wserver.c"
click node_ui_library "https://github.com/kris-dreemurr-dev/overos/blob/main/src/libs/libui/ui.c"
click node_ide_compiler "https://github.com/kris-dreemurr-dev/overos/blob/main/src/modules/redactor/compiler.c"
click node_doom "https://github.com/kris-dreemurr-dev/overos/blob/main/src/files/progs/DOOM/doomgeneric/d_main.c"
click node_quake "https://github.com/kris-dreemurr-dev/overos/blob/main/src/files/progs/Quake/quakegeneric/host.c"
click node_overcraft "https://github.com/kris-dreemurr-dev/overos/blob/main/src/files/progs/overCraft/main.cpp"
click node_overcraft_engine "https://github.com/kris-dreemurr-dev/overos/blob/main/src/files/progs/overCraft/engine/ovengine.h"

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_boot_menu,node_kernel_init,node_memory,node_user toneBlue
class node_syscalls,node_scheduler,node_user_permissions,node_terminal_login,node_shell toneAmber
class node_filesystem,node_block_registry,node_usb_controllers,node_audio_driver,node_network_driver toneMint
class node_desktop,node_window_server,node_ui_library,node_ide_compiler toneRose
class node_doom,node_quake,node_overcraft,node_overcraft_engine,node_bios toneIndigo
```

## Components

### Boot and kernel

- [Boot and VBE menu](https://github.com/kris-dreemurr-dev/overos/blob/main/src/boot/vbe_menu.c): `src/boot/vbe_menu.c`
- [Kernel initialization](https://github.com/kris-dreemurr-dev/overos/blob/main/src/kernel/main.c): `src/kernel/main.c`
- [Physical and virtual memory](https://github.com/kris-dreemurr-dev/overos/blob/main/src/memory/vmm.c): `src/memory/vmm.c`

### Processes and users

- [System call boundary](https://github.com/kris-dreemurr-dev/overos/blob/main/src/kernel/user_mode.c): `src/kernel/user_mode.c`
- [Process scheduler](https://github.com/kris-dreemurr-dev/overos/blob/main/src/kernel/sched.c): `src/kernel/sched.c`
- [Users and permissions](https://github.com/kris-dreemurr-dev/overos/blob/main/src/kernel/users.h): `src/kernel/users.h`
- [TTY and login](https://github.com/kris-dreemurr-dev/overos/blob/main/src/kernel/tty.h): `src/kernel/tty.h`
- [Ring 3 shell](https://github.com/kris-dreemurr-dev/overos/blob/main/src/programs/sh.c): `src/programs/sh.c`

### Devices and storage

- [VFS and FAT32](https://github.com/kris-dreemurr-dev/overos/blob/main/src/fs/fat32.c): `src/fs/fat32.c`
- [Block device registry](https://github.com/kris-dreemurr-dev/overos/blob/main/src/drivers/blk.h): `src/drivers/blk.h`
- [USB controllers](https://github.com/kris-dreemurr-dev/overos/blob/main/src/drivers/usb/xhci.c): `src/drivers/usb/xhci.c`
- [HDA audio](https://github.com/kris-dreemurr-dev/overos/blob/main/src/drivers/hda.c): `src/drivers/hda.c`
- [Ethernet](https://github.com/kris-dreemurr-dev/overos/blob/main/src/drivers/ethernet.c): `src/drivers/ethernet.c`

### Desktop and apps

- [Desktop compositor](https://github.com/kris-dreemurr-dev/overos/blob/main/src/files/progs/Desktop/desktop.c): `src/files/progs/Desktop/desktop.c`
- [Window server](https://github.com/kris-dreemurr-dev/overos/blob/main/src/files/progs/Desktop/wserver.c): `src/files/progs/Desktop/wserver.c`
- [UI library](https://github.com/kris-dreemurr-dev/overos/blob/main/src/libs/libui/ui.c): `src/libs/libui/ui.c`
- [IDE and C compiler](https://github.com/kris-dreemurr-dev/overos/blob/main/src/modules/redactor/compiler.c): `src/modules/redactor/compiler.c`

### Game ports

- [DOOM port](https://github.com/kris-dreemurr-dev/overos/blob/main/src/files/progs/DOOM/doomgeneric/d_main.c): `src/files/progs/DOOM/doomgeneric/d_main.c`
- [Quake port](https://github.com/kris-dreemurr-dev/overos/blob/main/src/files/progs/Quake/quakegeneric/host.c): `src/files/progs/Quake/quakegeneric/host.c`
- [overCraft game](https://github.com/kris-dreemurr-dev/overos/blob/main/src/files/progs/overCraft/main.cpp): `src/files/progs/overCraft/main.cpp`
- [3D rendering engine](https://github.com/kris-dreemurr-dev/overos/blob/main/src/files/progs/overCraft/engine/ovengine.h): `src/files/progs/overCraft/engine/ovengine.h`

### Other components

- **BIOS firmware**
- **Computer user**

## Connections

- BIOS firmware → Boot and VBE menu: starts boot
- Boot and VBE menu → Kernel initialization: loads kernel
- Kernel initialization → Physical and virtual memory: initializes memory
- Kernel initialization → TTY and login: starts terminal (evidence: `src/kernel/main.c`)
- Kernel initialization → Process scheduler: initializes scheduler
- Kernel initialization → USB controllers: initializes USB (evidence: `src/kernel/main.c`)
- Kernel initialization → VFS and FAT32: initializes storage (evidence: `src/kernel/main.c`)
- TTY and login → Users and permissions: loads accounts
- TTY and login → Ring 3 shell: starts shell
- Computer user → Ring 3 shell: enters commands
- Ring 3 shell → System call boundary: invokes services (evidence: `src/programs/sh.c`)
- System call boundary → Process scheduler: controls processes (evidence: `src/kernel/user_mode.c`)
- System call boundary → Physical and virtual memory: manages address spaces (evidence: `src/kernel/user_mode.c`)
- System call boundary → VFS and FAT32: performs file I/O (evidence: `src/kernel/user_mode.c`)
- USB controllers → Block device registry: registers disks (evidence: `src/drivers/blk.h`)
- Block device registry → VFS and FAT32: serves sectors (evidence: `src/drivers/blk.h`)
- Computer user → Desktop compositor: opens desktop
- Desktop compositor → Window server: composes windows
- Desktop compositor → UI library: uses widgets
- Computer user → IDE and C compiler: edits and builds
- Computer user → DOOM port: plays
- Computer user → Quake port: plays
- Computer user → overCraft game: plays
- overCraft game → 3D rendering engine: renders with (evidence: `src/files/progs/overCraft/main.cpp`)
- Kernel initialization → HDA audio: initializes audio (evidence: `src/kernel/main.c`)
- Kernel initialization → Ethernet: initializes network (evidence: `src/kernel/main.c`)
