# bluethefoxofficial/forest-os architecture

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

- Interactive diagram: https://gitdiagram.com/bluethefoxofficial/forest-os
- Repository: https://github.com/bluethefoxofficial/forest-os

## Overview

Forest OS is an educational Unix-like operating system spanning boot code, a kernel, libc, and userspace programs. Its principal workflow is booting into the kernel and providing userspace programs with system services; the tree also shows substantial memory, interrupt, graphics, input, and networking subsystems. The sampled excerpts support specific graphics, PS/2, TLB, memory-region, and authentication syscall relationships, but do not establish most boot, shell-dispatch, or kernel initialization wiring, so those links are omitted.

Main entry points: [`src/tlb_manager.c`](https://github.com/bluethefoxofficial/forest-os/blob/master/src/tlb_manager.c) (TLB management), [`src/ps2_controller.c`](https://github.com/bluethefoxofficial/forest-os/blob/master/src/ps2_controller.c) (PS/2 controller), [`src/graphics/window_manager.c`](https://github.com/bluethefoxofficial/forest-os/blob/master/src/graphics/window_manager.c) (Window manager), [`userspace/libc/auth.c`](https://github.com/bluethefoxofficial/forest-os/blob/master/userspace/libc/auth.c) (Auth wrappers)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_boot_kernel["Boot and kernel"]
  node_bios_boot["BIOS boot<br/>[bios_main.c]"]
  node_uefi_boot["UEFI boot<br/>[uefi_main.c]"]
  node_kernel["Kernel core<br/>[kernel.c]"]
  node_syscalls["Syscall interface<br/>[syscall.c]"]
  node_vfs["Virtual filesystem<br/>[vfs.c]"]
end

subgraph group_memory_interrupts["Memory and interrupts"]
  node_memory["Memory management<br/>[mm_init.c]"]
  node_region_protection["Region protection"]
  node_tlb["TLB management<br/>[tlb_manager.c]"]
  node_interrupts["Interrupt subsystem<br/>[interrupt.c]"]
  node_controller_abstraction["Controller abstraction"]
end

subgraph group_devices_graphics["Devices and graphics"]
  node_ps2["PS/2 controller<br/>[ps2_controller.c]"]
  node_keyboard["Keyboard input"]
  node_network["Networking<br/>[net.c]"]
  node_graphics["Graphics API<br/>[graphics_manager.c]"]
  node_window_manager["Window manager<br/>[window_manager.c]"]
end

subgraph group_userland["Userspace"]
  node_shell["Shell<br/>[shell.c]"]
  node_programs["User programs"]
end

subgraph group_libc["C library"]
  node_auth_libc["Auth wrappers<br/>[auth.c]"]
  node_libc_headers["Libc interfaces"]
end

node_user(("User"))

node_user -->|"interacts with"| node_shell
node_auth_libc -->|"invokes user syscall"| node_syscalls
node_window_manager -->|"draws through"| node_graphics
node_tlb -->|"supports mappings"| node_memory
node_ps2 -->|"provides controller I/O"| node_keyboard

click node_bios_boot "https://github.com/bluethefoxofficial/forest-os/blob/master/src/bios/bios_main.c"
click node_uefi_boot "https://github.com/bluethefoxofficial/forest-os/blob/master/src/uefi/uefi_main.c"
click node_kernel "https://github.com/bluethefoxofficial/forest-os/blob/master/src/kernel.c"
click node_syscalls "https://github.com/bluethefoxofficial/forest-os/blob/master/src/syscall.c"
click node_vfs "https://github.com/bluethefoxofficial/forest-os/blob/master/src/vfs.c"
click node_memory "https://github.com/bluethefoxofficial/forest-os/blob/master/src/mm_init.c"
click node_region_protection "https://github.com/bluethefoxofficial/forest-os/blob/master/src/memory_region_manager.c"
click node_tlb "https://github.com/bluethefoxofficial/forest-os/blob/master/src/tlb_manager.c"
click node_interrupts "https://github.com/bluethefoxofficial/forest-os/blob/master/src/interrupt.c"
click node_controller_abstraction "https://github.com/bluethefoxofficial/forest-os/blob/master/src/interrupt_controller_abstraction.c"
click node_ps2 "https://github.com/bluethefoxofficial/forest-os/blob/master/src/ps2_controller.c"
click node_keyboard "https://github.com/bluethefoxofficial/forest-os/blob/master/src/keyboard_interrupt_handler.c"
click node_network "https://github.com/bluethefoxofficial/forest-os/blob/master/src/net.c"
click node_graphics "https://github.com/bluethefoxofficial/forest-os/blob/master/src/graphics/graphics_manager.c"
click node_window_manager "https://github.com/bluethefoxofficial/forest-os/blob/master/src/graphics/window_manager.c"
click node_shell "https://github.com/bluethefoxofficial/forest-os/blob/master/userspace/shell.c"
click node_programs "https://github.com/bluethefoxofficial/forest-os/tree/master/userspace"
click node_auth_libc "https://github.com/bluethefoxofficial/forest-os/blob/master/userspace/libc/auth.c"
click node_libc_headers "https://github.com/bluethefoxofficial/forest-os/tree/master/libs/libc/include/libc"

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_bios_boot,node_uefi_boot,node_kernel,node_syscalls,node_vfs,node_user toneBlue
class node_memory,node_region_protection,node_tlb,node_interrupts,node_controller_abstraction toneAmber
class node_ps2,node_keyboard,node_network,node_graphics,node_window_manager toneMint
class node_shell,node_programs toneRose
class node_auth_libc,node_libc_headers toneIndigo
```

## Components

### Boot and kernel

- [BIOS boot](https://github.com/bluethefoxofficial/forest-os/blob/master/src/bios/bios_main.c): `src/bios/bios_main.c`
- [UEFI boot](https://github.com/bluethefoxofficial/forest-os/blob/master/src/uefi/uefi_main.c): `src/uefi/uefi_main.c`
- [Kernel core](https://github.com/bluethefoxofficial/forest-os/blob/master/src/kernel.c): `src/kernel.c`
- [Syscall interface](https://github.com/bluethefoxofficial/forest-os/blob/master/src/syscall.c): `src/syscall.c`
- [Virtual filesystem](https://github.com/bluethefoxofficial/forest-os/blob/master/src/vfs.c): `src/vfs.c`

### Memory and interrupts

- [Memory management](https://github.com/bluethefoxofficial/forest-os/blob/master/src/mm_init.c): `src/mm_init.c`
- [Region protection](https://github.com/bluethefoxofficial/forest-os/blob/master/src/memory_region_manager.c): `src/memory_region_manager.c`
- [TLB management](https://github.com/bluethefoxofficial/forest-os/blob/master/src/tlb_manager.c): `src/tlb_manager.c`
- [Interrupt subsystem](https://github.com/bluethefoxofficial/forest-os/blob/master/src/interrupt.c): `src/interrupt.c`
- [Controller abstraction](https://github.com/bluethefoxofficial/forest-os/blob/master/src/interrupt_controller_abstraction.c): `src/interrupt_controller_abstraction.c`

### Devices and graphics

- [PS/2 controller](https://github.com/bluethefoxofficial/forest-os/blob/master/src/ps2_controller.c): `src/ps2_controller.c`
- [Keyboard input](https://github.com/bluethefoxofficial/forest-os/blob/master/src/keyboard_interrupt_handler.c): `src/keyboard_interrupt_handler.c`
- [Networking](https://github.com/bluethefoxofficial/forest-os/blob/master/src/net.c): `src/net.c`
- [Graphics API](https://github.com/bluethefoxofficial/forest-os/blob/master/src/graphics/graphics_manager.c): `src/graphics/graphics_manager.c`
- [Window manager](https://github.com/bluethefoxofficial/forest-os/blob/master/src/graphics/window_manager.c): `src/graphics/window_manager.c`

### Userspace

- [Shell](https://github.com/bluethefoxofficial/forest-os/blob/master/userspace/shell.c): `userspace/shell.c`
- [User programs](https://github.com/bluethefoxofficial/forest-os/tree/master/userspace): `userspace`

### C library

- [Auth wrappers](https://github.com/bluethefoxofficial/forest-os/blob/master/userspace/libc/auth.c): `userspace/libc/auth.c`
- [Libc interfaces](https://github.com/bluethefoxofficial/forest-os/tree/master/libs/libc/include/libc): `libs/libc/include/libc`

### Other components

- **User**

## Connections

- User → Shell: interacts with
- Auth wrappers → Syscall interface: invokes user syscall
- Window manager → Graphics API: draws through
- TLB management → Memory management: supports mappings
- PS/2 controller → Keyboard input: provides controller I/O