# termuos-project/termuos architecture

> Architecture diagram of the GitHub repository termuos-project/termuos, 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/termuos-project/termuos
- Repository: https://github.com/termuos-project/termuos
- Video tour (about a minute): https://gitdiagram.com/termuos-project/termuos/video

## Overview

TermuOS is a learning-oriented x86_64 operating system. Its visible interaction loop starts at the terminal shell: users enter commands that inspect files, launch programs, or exercise networking; user programs can also use system calls to access kernel services. The kernel initializes memory, scheduling, devices, and filesystems, then creates a shell process. The README highlights multitasking, VFS, terminal, memory management, and drivers; the tree also shows user programs, networking, and IPC. Arrows follow the sampled startup, shell, syscall, exec, and TFS code; unsampled subsystem wiring is omitted where uncertain.

Main entry points: [`kernel/main.c`](https://github.com/termuos-project/termuos/blob/main/kernel/main.c) (Kernel startup), [`kernel/shell/shell.c`](https://github.com/termuos-project/termuos/blob/main/kernel/shell/shell.c) (Shell), [`kernel/user/syscall.c`](https://github.com/termuos-project/termuos/blob/main/kernel/user/syscall.c) (System calls), [`kernel/fs/vfs.c`](https://github.com/termuos-project/termuos/blob/main/kernel/fs/vfs.c) (VFS)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_boot["Kernel Core"]
  node_main["Kernel startup<br/>[main.c]"]
  node_memory["Memory management<br/>[pmm.c]"]
  node_vmm["Virtual memory<br/>[vmm.c]"]
  node_scheduler["Scheduler<br/>[scheduler.c]"]
  node_process["Processes<br/>[process.c]"]
  node_interrupts["x86 interrupts<br/>[idt.c]"]
end

subgraph group_io["Terminal And Devices"]
  node_shell["Shell<br/>[shell.c]"]
  node_terminal["Framebuffer terminal<br/>[terminal.c]"]
  node_keyboard["Keyboard input<br/>[keyboard.c]"]
  node_drivers["Device drivers<br/>[driver.c]"]
  node_network["Network stack<br/>[net.c]"]
  node_virtio_net["Virtio network<br/>[virtio_net.c]"]
end

subgraph group_fs["Files And Execution"]
  node_vfs["VFS<br/>[vfs.c]"]
  node_tfs["TFS filesystem<br/>[tfs.c]"]
  node_ramfs["RAM filesystem<br/>[ramfs.c]"]
  node_disk["Disk driver<br/>[disk.c]"]
  node_exec["ELF loader<br/>[exec.c]"]
end

subgraph group_user["User Services"]
  node_syscalls["System calls<br/>[syscall.c]"]
  node_programs["User programs<br/>[cat.c]"]
  node_ipc["IPC ports<br/>[port.c]"]
end

node_person(("User"))
node_hardware(("Hardware"))

node_person -->|"enters commands"| node_shell
node_main -->|"initializes"| node_interrupts
node_main -->|"initializes"| node_memory
node_main -->|"initializes"| node_vmm
node_main -->|"initializes"| node_keyboard
node_main -->|"initializes"| node_vfs
node_main -->|"mounts filesystem"| node_tfs
node_main -->|"fallback mount"| node_ramfs
node_main -->|"creates shell process"| node_process
node_main -->|"starts shell thread"| node_scheduler
node_shell -->|"prints output"| node_terminal
node_keyboard -->|"provides input"| node_shell
node_shell -->|"reads files"| node_vfs
node_shell -->|"launches executable"| node_exec
node_exec -->|"reads executable"| node_vfs
node_exec -->|"maps segments"| node_vmm
node_shell -->|"runs network commands"| node_network
node_network -->|"sends and polls packets"| node_virtio_net
node_virtio_net -->|"exchanges packets"| node_hardware
node_hardware -->|"device events"| node_drivers
node_programs -->|"requests kernel services"| node_syscalls
node_syscalls -->|"reads and writes files"| node_vfs
node_syscalls -->|"exits process"| node_process
node_syscalls -->|"dispatches port operations"| node_ipc
node_tfs -->|"reads and writes blocks"| node_disk

click node_main "https://github.com/termuos-project/termuos/blob/main/kernel/main.c"
click node_memory "https://github.com/termuos-project/termuos/blob/main/kernel/mm/pmm.c"
click node_vmm "https://github.com/termuos-project/termuos/blob/main/kernel/mm/vmm.c"
click node_scheduler "https://github.com/termuos-project/termuos/blob/main/kernel/sched/scheduler.c"
click node_process "https://github.com/termuos-project/termuos/blob/main/kernel/proc/process.c"
click node_interrupts "https://github.com/termuos-project/termuos/blob/main/kernel/arch/x86_64/idt.c"
click node_shell "https://github.com/termuos-project/termuos/blob/main/kernel/shell/shell.c"
click node_terminal "https://github.com/termuos-project/termuos/blob/main/kernel/drivers/video/terminal.c"
click node_keyboard "https://github.com/termuos-project/termuos/blob/main/kernel/drivers/input/keyboard.c"
click node_drivers "https://github.com/termuos-project/termuos/blob/main/kernel/drivers/driver.c"
click node_network "https://github.com/termuos-project/termuos/blob/main/kernel/net/net.c"
click node_virtio_net "https://github.com/termuos-project/termuos/blob/main/kernel/drivers/net/virtio_net.c"
click node_vfs "https://github.com/termuos-project/termuos/blob/main/kernel/fs/vfs.c"
click node_tfs "https://github.com/termuos-project/termuos/blob/main/kernel/fs/tfs.c"
click node_ramfs "https://github.com/termuos-project/termuos/blob/main/kernel/fs/ramfs.c"
click node_disk "https://github.com/termuos-project/termuos/blob/main/kernel/drivers/storage/disk.c"
click node_exec "https://github.com/termuos-project/termuos/blob/main/kernel/proc/exec.c"
click node_syscalls "https://github.com/termuos-project/termuos/blob/main/kernel/user/syscall.c"
click node_programs "https://github.com/termuos-project/termuos/blob/main/tsys/cat/cat.c"
click node_ipc "https://github.com/termuos-project/termuos/blob/main/kernel/ipc/port.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_main,node_memory,node_vmm,node_scheduler,node_process,node_interrupts,node_person toneBlue
class node_shell,node_terminal,node_keyboard,node_drivers,node_network,node_virtio_net toneAmber
class node_vfs,node_tfs,node_ramfs,node_disk,node_exec toneMint
class node_syscalls,node_programs,node_ipc toneRose
class node_hardware toneIndigo
```

## Components

### Kernel Core

- [Kernel startup](https://github.com/termuos-project/termuos/blob/main/kernel/main.c): `kernel/main.c`
- [Memory management](https://github.com/termuos-project/termuos/blob/main/kernel/mm/pmm.c): `kernel/mm/pmm.c`
- [Virtual memory](https://github.com/termuos-project/termuos/blob/main/kernel/mm/vmm.c): `kernel/mm/vmm.c`
- [Scheduler](https://github.com/termuos-project/termuos/blob/main/kernel/sched/scheduler.c): `kernel/sched/scheduler.c`
- [Processes](https://github.com/termuos-project/termuos/blob/main/kernel/proc/process.c): `kernel/proc/process.c`
- [x86 interrupts](https://github.com/termuos-project/termuos/blob/main/kernel/arch/x86_64/idt.c): `kernel/arch/x86_64/idt.c`

### Terminal And Devices

- [Shell](https://github.com/termuos-project/termuos/blob/main/kernel/shell/shell.c): `kernel/shell/shell.c`
- [Framebuffer terminal](https://github.com/termuos-project/termuos/blob/main/kernel/drivers/video/terminal.c): `kernel/drivers/video/terminal.c`
- [Keyboard input](https://github.com/termuos-project/termuos/blob/main/kernel/drivers/input/keyboard.c): `kernel/drivers/input/keyboard.c`
- [Device drivers](https://github.com/termuos-project/termuos/blob/main/kernel/drivers/driver.c): `kernel/drivers/driver.c`
- [Network stack](https://github.com/termuos-project/termuos/blob/main/kernel/net/net.c): `kernel/net/net.c`
- [Virtio network](https://github.com/termuos-project/termuos/blob/main/kernel/drivers/net/virtio_net.c): `kernel/drivers/net/virtio_net.c`

### Files And Execution

- [VFS](https://github.com/termuos-project/termuos/blob/main/kernel/fs/vfs.c): `kernel/fs/vfs.c`
- [TFS filesystem](https://github.com/termuos-project/termuos/blob/main/kernel/fs/tfs.c): `kernel/fs/tfs.c`
- [RAM filesystem](https://github.com/termuos-project/termuos/blob/main/kernel/fs/ramfs.c): `kernel/fs/ramfs.c`
- [Disk driver](https://github.com/termuos-project/termuos/blob/main/kernel/drivers/storage/disk.c): `kernel/drivers/storage/disk.c`
- [ELF loader](https://github.com/termuos-project/termuos/blob/main/kernel/proc/exec.c): `kernel/proc/exec.c`

### User Services

- [System calls](https://github.com/termuos-project/termuos/blob/main/kernel/user/syscall.c): `kernel/user/syscall.c`
- [User programs](https://github.com/termuos-project/termuos/blob/main/tsys/cat/cat.c): `tsys/cat/cat.c`
- [IPC ports](https://github.com/termuos-project/termuos/blob/main/kernel/ipc/port.c): `kernel/ipc/port.c`

### Other components

- **User**
- **Hardware**

## Connections

- User → Shell: enters commands
- Kernel startup → x86 interrupts: initializes
- Kernel startup → Memory management: initializes
- Kernel startup → Virtual memory: initializes
- Kernel startup → Keyboard input: initializes
- Kernel startup → VFS: initializes
- Kernel startup → TFS filesystem: mounts filesystem
- Kernel startup → RAM filesystem: fallback mount
- Kernel startup → Processes: creates shell process
- Kernel startup → Scheduler: starts shell thread
- Shell → Framebuffer terminal: prints output
- Keyboard input → Shell: provides input
- Shell → VFS: reads files
- Shell → ELF loader: launches executable
- ELF loader → VFS: reads executable
- ELF loader → Virtual memory: maps segments
- Shell → Network stack: runs network commands
- Network stack → Virtio network: sends and polls packets
- Virtio network → Hardware: exchanges packets
- Hardware → Device drivers: device events
- User programs → System calls: requests kernel services
- System calls → VFS: reads and writes files
- System calls → Processes: exits process
- System calls → IPC ports: dispatches port operations
- TFS filesystem → Disk driver: reads and writes blocks