# arbuz7277/arbuzos architecture

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

- Interactive diagram: https://gitdiagram.com/arbuz7277/arbuzos
- Repository: https://github.com/arbuz7277/arbuzos

## Overview

ArbuzOS is a learning-oriented 32-bit x86 operating system booted through an MBR. Its principal workflow is firmware boot into real-mode startup, transition to protected mode, then kernel initialization and VGA output; interrupt setup enables timer and keyboard handling. The tree also shows disk-access routines, panic reporting, and screen/keyboard helpers. The README documents the MBR boot and 32-bit OS, but most assembly was not sampled, so connections involving those modules are shown as unverified rather than asserted.

Main entry points: [`kernel/idt/idt.cpp`](https://github.com/arbuz7277/arbuzos/blob/main/kernel/idt/idt.cpp) (IDT Setup), [`boot.asm`](https://github.com/arbuz7277/arbuzos/blob/main/boot.asm) (MBR Startup), [`pmode.asm`](https://github.com/arbuz7277/arbuzos/blob/main/pmode.asm) (Protected Entry), [`kernel/kernel.cpp`](https://github.com/arbuz7277/arbuzos/blob/main/kernel/kernel.cpp) (Kernel Startup)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_boot["Boot and Disk"]
  node_boot["MBR Startup<br/>[boot.asm]"]
  node_dap["Disk Address Packet<br/>[dap.asm]"]
  node_lba["LBA Support<br/>[lba_support.asm]"]
end

subgraph group_mode["CPU Modes"]
  node_pmode_entry["Protected Entry<br/>[pmode.asm]"]
  node_gdt["GDT Setup<br/>[gdt.asm]"]
  node_real_print["Real-Mode Text<br/>[print_str.asm]"]
  node_protected_print["Protected Text<br/>[print_str.asm]"]
end

subgraph group_kernel["Kernel Core"]
  node_kernel_main["Kernel Startup<br/>[kernel.cpp]"]
  node_panic["Panic Reporter<br/>[kernel_panic.cpp]"]
  node_ports["Port I/O<br/>[ports.hpp]"]
end

subgraph group_interrupts["Interrupts"]
  node_idt["IDT Setup<br/>[idt.cpp]"]
  node_idt_layout["IDT Definitions<br/>[idt.hpp]"]
  node_isr["ISR Stubs<br/>[isr_stub.asm]"]
  node_double_fault["Double Fault<br/>[double_fault.asm]"]
  node_pic["PIC Remap<br/>[pic_remap.asm]"]
  node_timer["Timer IRQ<br/>[timer.asm]"]
  node_keyboard_irq["Keyboard IRQ<br/>[keyboard.asm]"]
end

subgraph group_io["Display and Input"]
  node_print["VGA Printer<br/>[print.cpp]"]
  node_print_api["Print API<br/>[print.hpp]"]
  node_idt_msg["Interrupt Messages<br/>[idt_msg.asm]"]
  node_putc["Character Output<br/>[putc.asm]"]
  node_hex["Hex Output<br/>[print_hex.asm]"]
  node_scancode["Scancode Handler"]
  node_keymap["US Keymap<br/>[keymap_us.asm]"]
end

node_firmware(("BIOS / User"))

node_firmware -->|"boots MBR"| node_boot
node_boot -.->|"uses disk access"| node_dap
node_boot -.->|"reads sectors"| node_lba
node_boot -.->|"prints text"| node_real_print
node_boot -.->|"enters protected mode"| node_pmode_entry
node_pmode_entry -.->|"loads GDT"| node_gdt
node_pmode_entry -.->|"prints text"| node_protected_print
node_pmode_entry -.->|"transfers control"| node_kernel_main
node_kernel_main -->|"initializes IDT"| node_idt
node_kernel_main -->|"remaps PIC"| node_pic
node_kernel_main -->|"prints banner"| node_print
node_idt -->|"uses definitions"| node_idt_layout
node_idt -->|"registers default handler"| node_isr
node_idt -->|"registers vector 8"| node_double_fault
node_idt -->|"registers vector 32"| node_timer
node_idt -->|"registers vector 33"| node_keyboard_irq
node_panic -->|"prints diagnostics"| node_print
node_print -->|"implements API"| node_print_api
node_print -.->|"writes VGA text"| node_putc
node_protected_print -.->|"renders characters"| node_putc
node_protected_print -.->|"formats hexadecimal"| node_hex
node_keyboard_irq -.->|"handles key input"| node_scancode
node_scancode -.->|"maps scancodes"| node_keymap
node_idt -.->|"reports interrupts"| node_idt_msg

click node_boot "https://github.com/arbuz7277/arbuzos/blob/main/boot.asm"
click node_dap "https://github.com/arbuz7277/arbuzos/blob/main/disks/dap.asm"
click node_lba "https://github.com/arbuz7277/arbuzos/blob/main/disks/lba_support.asm"
click node_pmode_entry "https://github.com/arbuz7277/arbuzos/blob/main/pmode.asm"
click node_gdt "https://github.com/arbuz7277/arbuzos/blob/main/protected_mode/gdt.asm"
click node_real_print "https://github.com/arbuz7277/arbuzos/blob/main/real_mode/print_str.asm"
click node_protected_print "https://github.com/arbuz7277/arbuzos/blob/main/protected_mode/print_str.asm"
click node_kernel_main "https://github.com/arbuz7277/arbuzos/blob/main/kernel/kernel.cpp"
click node_panic "https://github.com/arbuz7277/arbuzos/blob/main/kernel/kernel_panic.cpp"
click node_ports "https://github.com/arbuz7277/arbuzos/blob/main/kernel/include/ports.hpp"
click node_idt "https://github.com/arbuz7277/arbuzos/blob/main/kernel/idt/idt.cpp"
click node_idt_layout "https://github.com/arbuz7277/arbuzos/blob/main/kernel/include/idt.hpp"
click node_isr "https://github.com/arbuz7277/arbuzos/blob/main/kernel/idt/gates/isr_stub.asm"
click node_double_fault "https://github.com/arbuz7277/arbuzos/blob/main/kernel/idt/gates/double_fault.asm"
click node_pic "https://github.com/arbuz7277/arbuzos/blob/main/kernel/idt/pic_remap.asm"
click node_timer "https://github.com/arbuz7277/arbuzos/blob/main/kernel/idt/irq/timer.asm"
click node_keyboard_irq "https://github.com/arbuz7277/arbuzos/blob/main/kernel/idt/irq/keyboard.asm"
click node_print "https://github.com/arbuz7277/arbuzos/blob/main/kernel/drivers/print.cpp"
click node_print_api "https://github.com/arbuz7277/arbuzos/blob/main/kernel/include/print.hpp"
click node_idt_msg "https://github.com/arbuz7277/arbuzos/blob/main/kernel/idt/idt_msg.asm"
click node_putc "https://github.com/arbuz7277/arbuzos/blob/main/protected_mode/screen/putc.asm"
click node_hex "https://github.com/arbuz7277/arbuzos/blob/main/protected_mode/screen/print_hex.asm"
click node_scancode "https://github.com/arbuz7277/arbuzos/blob/main/protected_mode/screen/keyboard/handle_scancode.asm"
click node_keymap "https://github.com/arbuz7277/arbuzos/blob/main/protected_mode/screen/keyboard/keymap_us.asm"

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,node_dap,node_lba,node_firmware toneBlue
class node_pmode_entry,node_gdt,node_real_print,node_protected_print toneAmber
class node_kernel_main,node_panic,node_ports toneMint
class node_idt,node_idt_layout,node_isr,node_double_fault,node_pic,node_timer,node_keyboard_irq toneRose
class node_print,node_print_api,node_idt_msg,node_putc,node_hex,node_scancode,node_keymap toneIndigo
```

## Components

### Boot and Disk

- [MBR Startup](https://github.com/arbuz7277/arbuzos/blob/main/boot.asm): `boot.asm`
- [Disk Address Packet](https://github.com/arbuz7277/arbuzos/blob/main/disks/dap.asm): `disks/dap.asm`
- [LBA Support](https://github.com/arbuz7277/arbuzos/blob/main/disks/lba_support.asm): `disks/lba_support.asm`

### CPU Modes

- [Protected Entry](https://github.com/arbuz7277/arbuzos/blob/main/pmode.asm): `pmode.asm`
- [GDT Setup](https://github.com/arbuz7277/arbuzos/blob/main/protected_mode/gdt.asm): `protected_mode/gdt.asm`
- [Real-Mode Text](https://github.com/arbuz7277/arbuzos/blob/main/real_mode/print_str.asm): `real_mode/print_str.asm`
- [Protected Text](https://github.com/arbuz7277/arbuzos/blob/main/protected_mode/print_str.asm): `protected_mode/print_str.asm`

### Kernel Core

- [Kernel Startup](https://github.com/arbuz7277/arbuzos/blob/main/kernel/kernel.cpp): `kernel/kernel.cpp`
- [Panic Reporter](https://github.com/arbuz7277/arbuzos/blob/main/kernel/kernel_panic.cpp): `kernel/kernel_panic.cpp`
- [Port I/O](https://github.com/arbuz7277/arbuzos/blob/main/kernel/include/ports.hpp): `kernel/include/ports.hpp`

### Interrupts

- [IDT Setup](https://github.com/arbuz7277/arbuzos/blob/main/kernel/idt/idt.cpp): `kernel/idt/idt.cpp`
- [IDT Definitions](https://github.com/arbuz7277/arbuzos/blob/main/kernel/include/idt.hpp): `kernel/include/idt.hpp`
- [ISR Stubs](https://github.com/arbuz7277/arbuzos/blob/main/kernel/idt/gates/isr_stub.asm): `kernel/idt/gates/isr_stub.asm`
- [Double Fault](https://github.com/arbuz7277/arbuzos/blob/main/kernel/idt/gates/double_fault.asm): `kernel/idt/gates/double_fault.asm`
- [PIC Remap](https://github.com/arbuz7277/arbuzos/blob/main/kernel/idt/pic_remap.asm): `kernel/idt/pic_remap.asm`
- [Timer IRQ](https://github.com/arbuz7277/arbuzos/blob/main/kernel/idt/irq/timer.asm): `kernel/idt/irq/timer.asm`
- [Keyboard IRQ](https://github.com/arbuz7277/arbuzos/blob/main/kernel/idt/irq/keyboard.asm): `kernel/idt/irq/keyboard.asm`

### Display and Input

- [VGA Printer](https://github.com/arbuz7277/arbuzos/blob/main/kernel/drivers/print.cpp): `kernel/drivers/print.cpp`
- [Print API](https://github.com/arbuz7277/arbuzos/blob/main/kernel/include/print.hpp): `kernel/include/print.hpp`
- [Interrupt Messages](https://github.com/arbuz7277/arbuzos/blob/main/kernel/idt/idt_msg.asm): `kernel/idt/idt_msg.asm`
- [Character Output](https://github.com/arbuz7277/arbuzos/blob/main/protected_mode/screen/putc.asm): `protected_mode/screen/putc.asm`
- [Hex Output](https://github.com/arbuz7277/arbuzos/blob/main/protected_mode/screen/print_hex.asm): `protected_mode/screen/print_hex.asm`
- [Scancode Handler](https://github.com/arbuz7277/arbuzos/blob/main/protected_mode/screen/keyboard/handle_scancode.asm): `protected_mode/screen/keyboard/handle_scancode.asm`
- [US Keymap](https://github.com/arbuz7277/arbuzos/blob/main/protected_mode/screen/keyboard/keymap_us.asm): `protected_mode/screen/keyboard/keymap_us.asm`

### Other components

- **BIOS / User**

## Connections

- BIOS / User → MBR Startup: boots MBR (evidence: `README.md`)
- MBR Startup → Disk Address Packet: uses disk access
- MBR Startup → LBA Support: reads sectors
- MBR Startup → Real-Mode Text: prints text
- MBR Startup → Protected Entry: enters protected mode
- Protected Entry → GDT Setup: loads GDT
- Protected Entry → Protected Text: prints text
- Protected Entry → Kernel Startup: transfers control
- Kernel Startup → IDT Setup: initializes IDT (evidence: `kernel/kernel.cpp`)
- Kernel Startup → PIC Remap: remaps PIC (evidence: `kernel/kernel.cpp`)
- Kernel Startup → VGA Printer: prints banner (evidence: `kernel/kernel.cpp`)
- IDT Setup → IDT Definitions: uses definitions (evidence: `kernel/idt/idt.cpp`)
- IDT Setup → ISR Stubs: registers default handler (evidence: `kernel/idt/idt.cpp`)
- IDT Setup → Double Fault: registers vector 8 (evidence: `kernel/idt/idt.cpp`)
- IDT Setup → Timer IRQ: registers vector 32 (evidence: `kernel/idt/idt.cpp`)
- IDT Setup → Keyboard IRQ: registers vector 33 (evidence: `kernel/idt/idt.cpp`)
- Panic Reporter → VGA Printer: prints diagnostics (evidence: `kernel/kernel_panic.cpp`)
- VGA Printer → Print API: implements API (evidence: `kernel/drivers/print.cpp`)
- VGA Printer → Character Output: writes VGA text
- Protected Text → Character Output: renders characters
- Protected Text → Hex Output: formats hexadecimal
- Keyboard IRQ → Scancode Handler: handles key input
- Scancode Handler → US Keymap: maps scancodes
- IDT Setup → Interrupt Messages: reports interrupts
