# mhdsahil1/nyota-os architecture

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

- Interactive diagram: https://gitdiagram.com/mhdsahil1/nyota-os
- Repository: https://github.com/mhdsahil1/nyota-os

## Overview

Nyota OS is a small, experimental x86-32 hobby operating system. Its documented execution path starts at the assembly bootloader and proceeds into the kernel; the sampled kernel entry initializes serial and VGA output, descriptor tables, keyboard interrupts, and then the interactive shell. The shell reads keyboard input, dispatches built-in commands, and prints results through VGA (which also mirrors characters to serial). The README describes bootable-image and QEMU capabilities, but build and image-generation machinery is excluded. Links for unsampled boot details follow the documented architecture only.

Main entry points: [`kernel/kernel.c`](https://github.com/mhdsahil1/nyota-os/blob/main/kernel/kernel.c) (Kernel main), [`kernel/idt/idt.c`](https://github.com/mhdsahil1/nyota-os/blob/main/kernel/idt/idt.c) (IDT and PIC), [`kernel/vga/vga.c`](https://github.com/mhdsahil1/nyota-os/blob/main/kernel/vga/vga.c) (VGA console), [`kernel/keyboard/keyboard.c`](https://github.com/mhdsahil1/nyota-os/blob/main/kernel/keyboard/keyboard.c) (Keyboard driver)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_boot["Boot"]
  node_bootloader["Bootloader<br/>[boot.asm]"]
  node_entry["Kernel entry<br/>[kernel_entry.asm]"]
end

subgraph group_kernel["Kernel setup"]
  node_kernel_main["Kernel main<br/>[kernel.c]"]
  node_gdt["GDT setup<br/>[gdt.c]"]
  node_gdt_asm["GDT reload<br/>[gdt_flush.asm]"]
  node_idt["IDT and PIC<br/>[idt.c]"]
  node_idt_asm["Interrupt stubs<br/>[idt_asm.asm]"]
end

subgraph group_interaction["Shell interaction"]
  node_keyboard["Keyboard driver<br/>[keyboard.c]"]
  node_shell["Command shell<br/>[shell.c]"]
end

subgraph group_io["Hardware I/O"]
  node_vga["VGA console<br/>[vga.c]"]
  node_serial["Serial console<br/>[serial.c]"]
end

node_computer(("Computer"))
node_keyboard_hw(("PS/2 keyboard"))
node_vga_hw[("VGA framebuffer")]
node_serial_host(("Host serial"))
node_cpu(("x86 CPU"))

node_computer -->|"starts boot"| node_bootloader
node_bootloader -->|"transfers control"| node_entry
node_entry -->|"enters kernel"| node_kernel_main
node_kernel_main -->|"initializes"| node_serial
node_kernel_main -->|"initializes"| node_vga
node_kernel_main -->|"initializes"| node_gdt
node_kernel_main -->|"initializes"| node_idt
node_kernel_main -->|"initializes"| node_keyboard
node_kernel_main -->|"starts"| node_shell
node_gdt -->|"loads table"| node_gdt_asm
node_idt -->|"loads IDT"| node_idt_asm
node_idt -->|"configures interrupts"| node_cpu
node_keyboard -->|"registers IRQ handler"| node_idt
node_keyboard_hw -->|"sends scan codes"| node_keyboard
node_shell -->|"reads characters"| node_keyboard
node_shell -->|"prints commands"| node_vga
node_vga -->|"writes text"| node_vga_hw
node_vga -->|"mirrors characters"| node_serial
node_serial -->|"sends output"| node_serial_host

click node_bootloader "https://github.com/mhdsahil1/nyota-os/blob/main/bootloader/boot.asm"
click node_entry "https://github.com/mhdsahil1/nyota-os/blob/main/kernel/kernel_entry.asm"
click node_kernel_main "https://github.com/mhdsahil1/nyota-os/blob/main/kernel/kernel.c"
click node_gdt "https://github.com/mhdsahil1/nyota-os/blob/main/kernel/gdt/gdt.c"
click node_gdt_asm "https://github.com/mhdsahil1/nyota-os/blob/main/kernel/gdt/gdt_flush.asm"
click node_idt "https://github.com/mhdsahil1/nyota-os/blob/main/kernel/idt/idt.c"
click node_idt_asm "https://github.com/mhdsahil1/nyota-os/blob/main/kernel/idt/idt_asm.asm"
click node_keyboard "https://github.com/mhdsahil1/nyota-os/blob/main/kernel/keyboard/keyboard.c"
click node_shell "https://github.com/mhdsahil1/nyota-os/blob/main/kernel/shell/shell.c"
click node_vga "https://github.com/mhdsahil1/nyota-os/blob/main/kernel/vga/vga.c"
click node_serial "https://github.com/mhdsahil1/nyota-os/blob/main/kernel/serial/serial.c"

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_bootloader,node_entry toneBlue
class node_kernel_main,node_gdt,node_gdt_asm,node_idt,node_idt_asm,node_vga_hw toneAmber
class node_keyboard,node_shell toneMint
class node_vga,node_serial toneRose
class node_computer,node_keyboard_hw,node_serial_host,node_cpu toneIndigo
```

## Components

### Boot

- [Bootloader](https://github.com/mhdsahil1/nyota-os/blob/main/bootloader/boot.asm): `bootloader/boot.asm`
- [Kernel entry](https://github.com/mhdsahil1/nyota-os/blob/main/kernel/kernel_entry.asm): `kernel/kernel_entry.asm`

### Kernel setup

- [Kernel main](https://github.com/mhdsahil1/nyota-os/blob/main/kernel/kernel.c): `kernel/kernel.c`
- [GDT setup](https://github.com/mhdsahil1/nyota-os/blob/main/kernel/gdt/gdt.c): `kernel/gdt/gdt.c`
- [GDT reload](https://github.com/mhdsahil1/nyota-os/blob/main/kernel/gdt/gdt_flush.asm): `kernel/gdt/gdt_flush.asm`
- [IDT and PIC](https://github.com/mhdsahil1/nyota-os/blob/main/kernel/idt/idt.c): `kernel/idt/idt.c`
- [Interrupt stubs](https://github.com/mhdsahil1/nyota-os/blob/main/kernel/idt/idt_asm.asm): `kernel/idt/idt_asm.asm`

### Shell interaction

- [Keyboard driver](https://github.com/mhdsahil1/nyota-os/blob/main/kernel/keyboard/keyboard.c): `kernel/keyboard/keyboard.c`
- [Command shell](https://github.com/mhdsahil1/nyota-os/blob/main/kernel/shell/shell.c): `kernel/shell/shell.c`

### Hardware I/O

- [VGA console](https://github.com/mhdsahil1/nyota-os/blob/main/kernel/vga/vga.c): `kernel/vga/vga.c`
- [Serial console](https://github.com/mhdsahil1/nyota-os/blob/main/kernel/serial/serial.c): `kernel/serial/serial.c`

### Other components

- **Computer**
- **PS/2 keyboard**
- **VGA framebuffer**
- **Host serial**
- **x86 CPU**

## Connections

- Computer → Bootloader: starts boot
- Bootloader → Kernel entry: transfers control
- Kernel entry → Kernel main: enters kernel
- Kernel main → Serial console: initializes
- Kernel main → VGA console: initializes
- Kernel main → GDT setup: initializes
- Kernel main → IDT and PIC: initializes
- Kernel main → Keyboard driver: initializes
- Kernel main → Command shell: starts
- GDT setup → GDT reload: loads table
- IDT and PIC → Interrupt stubs: loads IDT
- IDT and PIC → x86 CPU: configures interrupts
- Keyboard driver → IDT and PIC: registers IRQ handler
- PS/2 keyboard → Keyboard driver: sends scan codes
- Command shell → Keyboard driver: reads characters
- Command shell → VGA console: prints commands
- VGA console → VGA framebuffer: writes text
- VGA console → Serial console: mirrors characters
- Serial console → Host serial: sends output