# shadokos/kfs architecture

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

- Interactive diagram: https://gitdiagram.com/shadokos/kfs
- Repository: https://github.com/shadokos/kfs

## Overview

##### Project type and purpose
- This is a monolithic, UNIX-like kernel for i386, written entirely in Zig.
- It provides core OS services (memory management, task scheduling, device drivers, syscall interface) plus a kernel-mode shell and basic CI/test harnesses.
- Key use cases: boot under GRUB or Limine, run on real or emulated hardware (QEMU), exercise memory and multitasking features, and support a minimal userspace POC.

##### File structure
- Top-level:
- CI/ : custom CI scripts, Dockerfile, ISO boot configs
- build.zig & build/ : Zig and Makefile wrappers for building the kernel, bootloader integration, ISO creation, QEMU launch
- iso/ : generated ISO boot images (GRUB and Limine folders)
- src/ : all kernel source code (boot, drivers, memory, task scheduler, shell, syscalls, etc.)
- src/ subdivided by subsystem:
- drivers/ : ACPI, PIC, PIT, PS2, serial port, VGA
- memory/ : allocators (buddy, slab, multipool, page-grained), paging, mapping, virtual space
- task/ : scheduler, ready queue, user-space trampoline, semaphores, signals
- tty/ : buffer writer, keyboard, themes, vt100 emulation
- syscall/ : individual syscall implementations
- shell/ : built-in commands for CI and default shell
- misc/ : logging, ASCII art, random, basic data structures
- Build and CI:
- .github/, CI/, Makefile, build.zig, build/Makefiles/ orchestrate compilation, testing, linting, ISO creation, and QEMU runs

##### README for additional insights
- Features list confirms core subsystems (Terminal, Memory, Multitasking) and pending parts (filesystem, signals, ELF exec).
- Testing section highlights serial port and CI integration.

##### Main components & interactions
a. Main components:
1. Hardware Layer (i386 CPU, physical RAM, I/O buses)
2. Bootloader Layer (GRUB / Limine)
3. Kernel Initialization
4. Memory Management Subsystem
- Page frame allocator (buddy)
- Virtual space allocator (AVL trees)
- Object allocators (slab, multipool, page-grained)
5. Device Drivers
- PS/2, VGA, Serial, PIC, PIT, ACPI
6. Task Scheduler & Multitasking
- Ready queue, context switching, semaphores, signals
7. System Call Interface
8. Kernel-mode Shell (terminal + built-ins)
9. Userspace POC (ELF loader pending)
10. CI / Build System
- Zig build scripts, Makefiles, Docker, QEMU emulator

b. Relationships & interactions:
- Bootloader → Loads Kernel (entry point, passes multiboot2 or limine info)
- Kernel Initialization → Sets up GDT, IDT, paging (HIGHER HALF mapping)
- Drivers ↔ Hardware: controllers and devices accessed via I/O ports and memory-mapped I/O
- Memory Subsystem ↔ Kernel & Tasks: allocates pages, objects, handles page faults
- Scheduler ↔ Memory ↔ Tasks: context switch uses page tables, allocates stacks
- Syscall Interface: user tasks invoke kernel services
- Shell ↔ Syscall Interface: runs built-in commands in kernel mode
- CI / Build System ↔ Source: triggers compile, link, ISO image, QEMU test harness

c. Architectural patterns & principles:
- Monolithic kernel: all core services linked in one binary
- Layered initialization: hardware abstraction then subsystems
- Modular code organization by subsystem under src/
- Build-time dependency graph via Zig and Makefiles
- Emulation & testing integrated in CI pipelines

d. Technologies, frameworks, libraries:
- Zig language for kernel and build scripts
- GNU Make + custom Makefiles (CI.mk, Docker.mk, Limine.mk, Zig.mk)
- GRUB and Limine bootloaders
- QEMU for emulation
- Docker for isolated CI runs

##### Detailed breakdown to capture essential elements
- Initialization flow: startup.asm (trampoline) → boot.zig → init subsystems.
- CI pipeline step (lint → build → test on QEMU → ISO generation).
- Don’t overload with every .zig file—group by subsystem folders.

- How the kernel boots and initializes
- The core OS subsystems and their interactions
- The build/test pipeline that produces and validates the kernel
- The boundary between hardware, kernel, and (future) userspace components

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph "Build & CI Pipeline"
        direction TB
        Source["Source Code (src/, build.zig, Makefile)"]:::buildCI
        Lint["Lint & Static Analysis"]:::buildCI
        Compile["Compile Kernel Binary"]:::buildCI
        ISO["Create ISO (GRUB & Limine)"]:::buildCI
        EmuTest["Run QEMU Tests"]:::buildCI
        CIW["GitHub Actions"]:::buildCI
        CIW --> Source
        Source --> Lint --> Compile --> ISO --> EmuTest
    end

    subgraph "Bootloader Layer"
        direction TB
        GRUB["GRUB Integration"]:::bootload
        Limine["Limine Integration"]:::bootload
    end

    subgraph "Kernel Initialization"
        direction TB
        Entry["Entry Point\n(trampoline & boot.zig)"]:::kernel
        GDT["GDT Setup (gdt.zig)"]:::kernel
        IDT["IDT Setup (interrupts.zig)"]:::kernel
        PagingInit["Paging & Higher-half Mapping"]:::kernel
        Entry --> GDT --> IDT --> PagingInit
    end

    subgraph "Kernel Core Subsystems"
        direction TB
        Memory["Memory Management Subsystem"]:::kernel
        Drivers["Device Drivers"]:::kernel
        Scheduler["Task Scheduler & Multitasking"]:::kernel
        Syscall["System Call Interface"]:::kernel
        Shell["Kernel-mode Shell"]:::kernel
        Memory --> Drivers
        Memory --> Scheduler
        Scheduler --> Syscall
        Shell -.-> Syscall
        Drivers <--> Hardware
    end

    Hardware["Hardware & Emulation\n(CPU, RAM, I/O, QEMU)"]:::hardware

    %% Connections
    Compile --> GRUB
    Compile --> Limine
    GRUB --> Entry
    Limine --> Entry
    Entry --> Memory
    Entry --> Drivers
    Entry --> Scheduler
    ISO --> Hardware
    EmuTest --> Hardware

    %% Click Events
    click Hardware "https://github.com/shadokos/kfs/blob/main/src/cpu.zig"
    click Hardware "https://github.com/shadokos/kfs/blob/main/src/interrupts.zig"
    click Hardware "https://github.com/shadokos/kfs/blob/main/src/trampoline.zig"
    click Hardware "https://github.com/shadokos/kfs/blob/main/src/multiboot.zig"
    click GRUB "https://github.com/shadokos/kfs/blob/main/build/bootloaders/grub.zig"
    click Limine "https://github.com/shadokos/kfs/blob/main/build/bootloaders/limine.zig"
    click Entry "https://github.com/shadokos/kfs/blob/main/src/boot.zig"
    click GDT "https://github.com/shadokos/kfs/blob/main/src/gdt.zig"
    click IDT "https://github.com/shadokos/kfs/blob/main/src/interrupts.zig"
    click Memory "https://github.com/shadokos/kfs/blob/main/src/memory/page_frame_allocator.zig"
    click Memory "https://github.com/shadokos/kfs/blob/main/src/memory/buddy_allocator.zig"
    click Memory "https://github.com/shadokos/kfs/blob/main/src/memory/paging.zig"
    click Memory "https://github.com/shadokos/kfs/blob/main/src/memory/mapping.zig"
    click Memory "https://github.com/shadokos/kfs/blob/main/src/memory/virtual_space.zig"
    click Memory "https://github.com/shadokos/kfs/blob/main/src/memory/virtual_space_allocator.zig"
    click Memory "https://github.com/shadokos/kfs/blob/main/src/memory/object_allocators/slab/slab.zig"
    click Memory "https://github.com/shadokos/kfs/blob/main/src/memory/object_allocators/multipool_allocator.zig"
    click Memory "https://github.com/shadokos/kfs/blob/main/src/memory/object_allocators/page_grained_allocator.zig"
    click Drivers "https://github.com/shadokos/kfs/blob/main/src/drivers/acpi/acpi.zig"
    click Drivers "https://github.com/shadokos/kfs/blob/main/src/drivers/pic/pic.zig"
    click Drivers "https://github.com/shadokos/kfs/blob/main/src/drivers/pit/pit.zig"
    click Drivers "https://github.com/shadokos/kfs/blob/main/src/drivers/ps2/ps2.zig"
    click Drivers "https://github.com/shadokos/kfs/blob/main/src/drivers/serial_port/serial.zig"
    click Drivers "https://github.com/shadokos/kfs/blob/main/src/drivers/vga/text.zig"
    click Scheduler "https://github.com/shadokos/kfs/blob/main/src/task/scheduler.zig"
    click Scheduler "https://github.com/shadokos/kfs/blob/main/src/task/ready_queue.zig"
    click Scheduler "https://github.com/shadokos/kfs/blob/main/src/task/ucontext.zig"
    click Scheduler "https://github.com/shadokos/kfs/blob/main/src/task/task.zig"
    click Scheduler "https://github.com/shadokos/kfs/blob/main/src/task/semaphore.zig"
    click Scheduler "https://github.com/shadokos/kfs/blob/main/src/task/signal.zig"
    click Scheduler "https://github.com/shadokos/kfs/blob/main/src/task/userspace.zig"
    click Scheduler "https://github.com/shadokos/kfs/blob/main/src/task/wait.zig"
    click Syscall "https://github.com/shadokos/kfs/blob/main/src/syscall.zig"
    click Syscall "https://github.com/shadokos/kfs/blob/main/src/syscall/exit.zig"
    click Syscall "https://github.com/shadokos/kfs/blob/main/src/syscall/fork.zig"
    click Syscall "https://github.com/shadokos/kfs/blob/main/src/syscall/write.zig"
    click Syscall "https://github.com/shadokos/kfs/blob/main/src/syscall/mmap.zig"
    click Shell "https://github.com/shadokos/kfs/blob/main/src/shell/Shell.zig"
    click Shell "https://github.com/shadokos/kfs/blob/main/src/shell/ci/builtins.zig"
    click Shell "https://github.com/shadokos/kfs/blob/main/src/shell/ci/shell.zig"
    click Shell "https://github.com/shadokos/kfs/blob/main/src/shell/default/builtins.zig"
    click Shell "https://github.com/shadokos/kfs/blob/main/src/shell/default/shell.zig"
    click EmuTest "https://github.com/shadokos/kfs/blob/main/.github/workflows/build.yml"
    click EmuTest "https://github.com/shadokos/kfs/blob/main/.github/workflows/unit_tests.yml"
    click CIW "https://github.com/shadokos/kfs/blob/main/CI/run_ci.sh"
    click CIW "https://github.com/shadokos/kfs/blob/main/CI/ci_core.py"
    click Source "https://github.com/shadokos/kfs/blob/main/build.zig"
    click Source "https://github.com/shadokos/kfs/tree/main/Makefile"
    click ISO "https://github.com/shadokos/kfs/blob/main/build/iso.zig"
    click Compile "https://github.com/shadokos/kfs/blob/main/build/kernel.zig"
    click EmuTest "https://github.com/shadokos/kfs/blob/main/build/qemu.zig"
    click ISO "https://github.com/shadokos/kfs/blob/main/CI/iso/boot/grub/grub.cfg"
    click ISO "https://github.com/shadokos/kfs/blob/main/CI/iso/boot/limine/limine.conf"

    %% Styles
    classDef buildCI fill:#bbf,stroke:#88f,color:#000;
    classDef bootload fill:#bfb,stroke:#8f8,color:#000;
    classDef kernel fill:#fb8,stroke:#f80,color:#000;
    classDef hardware fill:#ccc,stroke:#888,color:#000;
```
