# turbo-forcing/scooveos architecture

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

- Interactive diagram: https://gitdiagram.com/turbo-forcing/scooveos
- Repository: https://github.com/turbo-forcing/scooveos

## Overview

ScooveOS is a small 32-bit x86 operating system. The principal workflow is interactive: keyboard input reaches the shell, which dispatches commands to kernel services and reports results through the VGA console; file commands use either the RAM filesystem or FAT16 disk support. A second documented workflow loads and runs Ring 3 ELF programs through task management and system calls. The graph preserves the README’s hardware, memory, filesystem, shell, and multitasking capabilities. Edges are limited to documented relationships or relationships visible in indexed excerpts; unsampled wiring is omitted.

Main entry points: [`src/kernel/kernel.c`](https://github.com/turbo-forcing/scooveos/blob/master/src/kernel/kernel.c) (Kernel Initialization), [`src/kernel/syscall.c`](https://github.com/turbo-forcing/scooveos/blob/master/src/kernel/syscall.c) (System Calls), [`src/task/task.c`](https://github.com/turbo-forcing/scooveos/blob/master/src/task/task.c) (Task Scheduler), [`src/shell/shell.c`](https://github.com/turbo-forcing/scooveos/blob/master/src/shell/shell.c) (Command Shell)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interaction["Shell and Console"]
  node_shell["Command Shell<br/>[shell.c]"]
  node_console["VGA Console<br/>[vga.c]"]
end

subgraph group_hardware["Hardware Drivers"]
  node_keyboard["PS/2 Keyboard<br/>[keyboard.c]"]
  node_mouse["PS/2 Mouse<br/>[mouse.c]"]
  node_pit["Timer<br/>[pit.c]"]
  node_rtc["Real-Time Clock<br/>[rtc.c]"]
  node_ata["ATA Disk<br/>[ata.c]"]
end

subgraph group_storage["Filesystems"]
  node_ramfs[("RAM Filesystem<br/>[fs.c]")]
  node_fat16[("FAT16 Filesystem<br/>[fat16.c]")]
end

subgraph group_kernel["Kernel Services"]
  node_kernel_entry["Kernel Initialization<br/>[kernel.c]"]
  node_interrupts["Interrupt Handling<br/>[idt.c]"]
  node_gdt["GDT and TSS<br/>[gdt.c]"]
  node_memory["Physical Memory<br/>[mm.c]"]
  node_paging["Virtual Memory<br/>[paging.c]"]
  node_elf["ELF Loader<br/>[elf.c]"]
  node_tasks["Task Scheduler<br/>[task.c]"]
  node_syscalls["System Calls<br/>[syscall.c]"]
end

subgraph group_userspace["User Programs"]
  node_user_app["User Demo<br/>[main.c]"]
  node_userlib["User Library<br/>[syscall.c]"]
end

node_operator(("Operator"))

node_operator -->|"types on"| node_keyboard
node_keyboard -->|"delivers input"| node_shell
node_shell -->|"prints results"| node_console
node_shell -->|"runs file commands"| node_ramfs
node_shell -->|"runs disk commands"| node_fat16
node_fat16 -->|"reads and writes"| node_ata
node_kernel_entry -->|"initializes"| node_console
node_kernel_entry -->|"initializes"| node_interrupts
node_kernel_entry -->|"initializes"| node_gdt
node_kernel_entry -->|"initializes"| node_keyboard
node_kernel_entry -->|"initializes"| node_mouse
node_kernel_entry -->|"initializes"| node_pit
node_kernel_entry -->|"initializes"| node_rtc
node_kernel_entry -->|"initializes"| node_ata
node_kernel_entry -->|"initializes"| node_ramfs
node_kernel_entry -->|"mounts disk"| node_fat16
node_kernel_entry -->|"initializes"| node_memory
node_kernel_entry -->|"initializes"| node_paging
node_kernel_entry -->|"initializes"| node_tasks
node_kernel_entry -->|"initializes"| node_syscalls
node_interrupts -->|"requests scheduling"| node_tasks
node_tasks -->|"allocates memory"| node_memory
node_tasks -->|"manages address spaces"| node_paging
node_tasks -->|"loads user ELF"| node_elf
node_tasks -->|"uses TSS"| node_gdt
node_syscalls -->|"controls processes"| node_tasks
node_syscalls -->|"accesses files"| node_ramfs
node_syscalls -->|"reads time"| node_rtc
node_syscalls -->|"loads executable"| node_elf
node_syscalls -->|"maps user pages"| node_paging
node_syscalls -->|"accesses disk files"| node_fat16
node_user_app -->|"uses wrappers"| node_userlib
node_userlib -->|"invokes int 0x80"| node_syscalls

click node_shell "https://github.com/turbo-forcing/scooveos/blob/master/src/shell/shell.c"
click node_console "https://github.com/turbo-forcing/scooveos/blob/master/src/drivers/vga.c"
click node_keyboard "https://github.com/turbo-forcing/scooveos/blob/master/src/drivers/keyboard.c"
click node_mouse "https://github.com/turbo-forcing/scooveos/blob/master/src/drivers/mouse.c"
click node_pit "https://github.com/turbo-forcing/scooveos/blob/master/src/drivers/pit.c"
click node_rtc "https://github.com/turbo-forcing/scooveos/blob/master/src/drivers/rtc.c"
click node_ata "https://github.com/turbo-forcing/scooveos/blob/master/src/drivers/ata.c"
click node_ramfs "https://github.com/turbo-forcing/scooveos/blob/master/src/fs/fs.c"
click node_fat16 "https://github.com/turbo-forcing/scooveos/blob/master/src/fs/fat16.c"
click node_kernel_entry "https://github.com/turbo-forcing/scooveos/blob/master/src/kernel/kernel.c"
click node_interrupts "https://github.com/turbo-forcing/scooveos/blob/master/src/kernel/idt.c"
click node_gdt "https://github.com/turbo-forcing/scooveos/blob/master/src/kernel/gdt.c"
click node_memory "https://github.com/turbo-forcing/scooveos/blob/master/src/mm/mm.c"
click node_paging "https://github.com/turbo-forcing/scooveos/blob/master/src/mm/paging.c"
click node_elf "https://github.com/turbo-forcing/scooveos/blob/master/src/mm/elf.c"
click node_tasks "https://github.com/turbo-forcing/scooveos/blob/master/src/task/task.c"
click node_syscalls "https://github.com/turbo-forcing/scooveos/blob/master/src/kernel/syscall.c"
click node_user_app "https://github.com/turbo-forcing/scooveos/blob/master/user/main.c"
click node_userlib "https://github.com/turbo-forcing/scooveos/blob/master/user/userlib/syscall.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_shell,node_console toneBlue
class node_keyboard,node_mouse,node_pit,node_rtc,node_ata toneAmber
class node_ramfs,node_fat16 toneMint
class node_kernel_entry,node_interrupts,node_gdt,node_memory,node_paging,node_elf,node_tasks,node_syscalls toneRose
class node_user_app,node_userlib,node_operator toneIndigo
```

## Components

### Shell and Console

- [Command Shell](https://github.com/turbo-forcing/scooveos/blob/master/src/shell/shell.c): `src/shell/shell.c`
- [VGA Console](https://github.com/turbo-forcing/scooveos/blob/master/src/drivers/vga.c): `src/drivers/vga.c`

### Hardware Drivers

- [PS/2 Keyboard](https://github.com/turbo-forcing/scooveos/blob/master/src/drivers/keyboard.c): `src/drivers/keyboard.c`
- [PS/2 Mouse](https://github.com/turbo-forcing/scooveos/blob/master/src/drivers/mouse.c): `src/drivers/mouse.c`
- [Timer](https://github.com/turbo-forcing/scooveos/blob/master/src/drivers/pit.c): `src/drivers/pit.c`
- [Real-Time Clock](https://github.com/turbo-forcing/scooveos/blob/master/src/drivers/rtc.c): `src/drivers/rtc.c`
- [ATA Disk](https://github.com/turbo-forcing/scooveos/blob/master/src/drivers/ata.c): `src/drivers/ata.c`

### Filesystems

- [RAM Filesystem](https://github.com/turbo-forcing/scooveos/blob/master/src/fs/fs.c): `src/fs/fs.c`
- [FAT16 Filesystem](https://github.com/turbo-forcing/scooveos/blob/master/src/fs/fat16.c): `src/fs/fat16.c`

### Kernel Services

- [Kernel Initialization](https://github.com/turbo-forcing/scooveos/blob/master/src/kernel/kernel.c): `src/kernel/kernel.c`
- [Interrupt Handling](https://github.com/turbo-forcing/scooveos/blob/master/src/kernel/idt.c): `src/kernel/idt.c`
- [GDT and TSS](https://github.com/turbo-forcing/scooveos/blob/master/src/kernel/gdt.c): `src/kernel/gdt.c`
- [Physical Memory](https://github.com/turbo-forcing/scooveos/blob/master/src/mm/mm.c): `src/mm/mm.c`
- [Virtual Memory](https://github.com/turbo-forcing/scooveos/blob/master/src/mm/paging.c): `src/mm/paging.c`
- [ELF Loader](https://github.com/turbo-forcing/scooveos/blob/master/src/mm/elf.c): `src/mm/elf.c`
- [Task Scheduler](https://github.com/turbo-forcing/scooveos/blob/master/src/task/task.c): `src/task/task.c`
- [System Calls](https://github.com/turbo-forcing/scooveos/blob/master/src/kernel/syscall.c): `src/kernel/syscall.c`

### User Programs

- [User Demo](https://github.com/turbo-forcing/scooveos/blob/master/user/main.c): `user/main.c`
- [User Library](https://github.com/turbo-forcing/scooveos/blob/master/user/userlib/syscall.c): `user/userlib/syscall.c`

### Other components

- **Operator**

## Connections

- Operator → PS/2 Keyboard: types on (evidence: `README.md`)
- PS/2 Keyboard → Command Shell: delivers input (evidence: `src/drivers/keyboard.c`)
- Command Shell → VGA Console: prints results (evidence: `src/shell/shell.c`)
- Command Shell → RAM Filesystem: runs file commands (evidence: `src/shell/shell.c`)
- Command Shell → FAT16 Filesystem: runs disk commands (evidence: `src/shell/shell.c`)
- FAT16 Filesystem → ATA Disk: reads and writes (evidence: `src/fs/fat16.c`)
- Kernel Initialization → VGA Console: initializes (evidence: `README.md`)
- Kernel Initialization → Interrupt Handling: initializes (evidence: `README.md`)
- Kernel Initialization → GDT and TSS: initializes (evidence: `README.md`)
- Kernel Initialization → PS/2 Keyboard: initializes (evidence: `README.md`)
- Kernel Initialization → PS/2 Mouse: initializes (evidence: `README.md`)
- Kernel Initialization → Timer: initializes (evidence: `README.md`)
- Kernel Initialization → Real-Time Clock: initializes (evidence: `README.md`)
- Kernel Initialization → ATA Disk: initializes (evidence: `README.md`)
- Kernel Initialization → RAM Filesystem: initializes (evidence: `README.md`)
- Kernel Initialization → FAT16 Filesystem: mounts disk (evidence: `README.md`)
- Kernel Initialization → Physical Memory: initializes (evidence: `README.md`)
- Kernel Initialization → Virtual Memory: initializes (evidence: `README.md`)
- Kernel Initialization → Task Scheduler: initializes (evidence: `README.md`)
- Kernel Initialization → System Calls: initializes (evidence: `README.md`)
- Interrupt Handling → Task Scheduler: requests scheduling (evidence: `src/kernel/idt.c`)
- Task Scheduler → Physical Memory: allocates memory (evidence: `src/task/task.c`)
- Task Scheduler → Virtual Memory: manages address spaces (evidence: `src/task/task.c`)
- Task Scheduler → ELF Loader: loads user ELF (evidence: `src/task/task.c`)
- Task Scheduler → GDT and TSS: uses TSS (evidence: `src/task/task.c`)
- System Calls → Task Scheduler: controls processes (evidence: `src/kernel/syscall.c`)
- System Calls → RAM Filesystem: accesses files (evidence: `src/kernel/syscall.c`)
- System Calls → Real-Time Clock: reads time (evidence: `src/kernel/syscall.c`)
- System Calls → ELF Loader: loads executable (evidence: `src/kernel/syscall.c`)
- System Calls → Virtual Memory: maps user pages (evidence: `src/kernel/syscall.c`)
- System Calls → FAT16 Filesystem: accesses disk files (evidence: `src/kernel/syscall.c`)
- User Demo → User Library: uses wrappers (evidence: `user/main.c`)
- User Library → System Calls: invokes int 0x80 (evidence: `README.md`)
