# gitcomit8/serix architecture

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

- Interactive diagram: https://gitdiagram.com/gitcomit8/serix
- Repository: https://github.com/gitcomit8/serix

## Overview

##### Project type and purpose
- This is a bare-metal operating system kernel (“Serix”) written in Rust, booted with the Limine bootloader.
- Its goal is to initialize hardware (CPU, interrupts, memory, console framebuffer) and paint the screen blue on success.

##### File structure
- Top-level crates (Rust sub-projects) each implement a core kernel subsystem:
- kernel/         – entry point, GDT, syscalls, linker script
- hal/            – CPU, I/O primitives, serial, topology
- idt/            – Interrupt Descriptor Table setup
- apic/           – Local/APIC timer and I/O APIC
- memory/         – Paging, heap allocator
- task/           – async task executor, context switching
- graphics/       – framebuffer console, font rendering
- keyboard/       – keyboard driver
- capability/     – access rights/types store
- util/           – panic handler, helper routines
- Build automation: Makefile builds all crates, assembles an ISO with Limine, and runs QEMU.
- docs/ contains design docs for boot, HAL API, interrupt handling, etc.

##### README
- Confirms it’s a no-std OS kernel.
- Describes boot flow (Limine ➔ kernel).
- Lists subsystems matching the crates.

##### Main components & interactions
a. Bootloader (Limine)
– BIOS/UEFI ⇒ loads kernel ELF, hands off control to kernel entry.
b. Kernel entry (kernel/src/main.rs)
– sets up GDT, loads IDT module, calls HAL init.
c. HAL layer
– initializes CPU features, serial port for debugging, I/O primitives, CPU topology.
d. Memory manager
– sets up page tables, enables paging, initializes heap allocator.
e. Interrupt subsystem
– idt module registers handlers; apic configures LAPIC timer & routes IRQs.
f. Task scheduler & async executor
– context switches between tasks, handles wakes/yield.
g. Device drivers
– keyboard driver for PS/2 or USB keyboard input.
h. Graphics console
– writes characters to framebuffer, font lookup, clears screen to blue.
i. Capability & Utility crates
– share types, security primitives, panic handler.

##### Architectural patterns & principles
- Modular monolithic kernel: subsystems are independent Rust crates.
- Layered boot flow: Limine ➔ kernel core ➔ HAL ➔ subsystems.
- Separation of concerns: memory, CPU, interrupts, devices are decoupled.
- No-std environment: no OS dependencies, direct hardware access.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Layer 1: Bootloader
    subgraph "Layer 1: Bootloader" 
        direction TB
        Bootloader["Bootloader (Limine)"]:::boot
    end

    %% Layer 2: Kernel Core
    subgraph "Layer 2: Kernel Core"
        direction TB
        KernelMain["kernel/src/main.rs"]:::kernel
        GDT["kernel/src/gdt.rs"]:::kernel
        Syscall["kernel/src/syscall.rs"]:::kernel
        LinkerScript["kernel/linker.ld"]:::kernel
    end

    %% Layer 3: HAL
    subgraph "Layer 3: HAL / CPU Primitives"
        direction TB
        HALLib["hal/src/lib.rs"]:::subsys
        CPUInit["hal/src/cpu.rs"]:::subsys
        IOPrims["hal/src/io.rs"]:::subsys
        Serial["hal/src/serial.rs"]:::subsys
        Topology["hal/src/topology.rs"]:::subsys
    end

    %% Layer 4: Memory, Interrupts & Task Scheduler
    subgraph "Layer 4: Memory, Interrupts & Task Scheduler"
        direction TB
        MemoryLib["memory/src/lib.rs"]:::subsys
        HeapAlloc["memory/src/heap.rs"]:::subsys
        IDTLib["idt/src/lib.rs"]:::subsys
        APICLib["apic/src/lib.rs"]:::subsys
        IOAPIC["apic/src/ioapic.rs"]:::subsys
        Timer["apic/src/timer.rs"]:::subsys
        TaskLib["task/src/lib.rs"]:::subsys
        Executor["task/src/executor.rs"]:::subsys
        AsyncTask["task/src/async_task.rs"]:::subsys
        ContextSwitch["task/src/context_switch.rs"]:::subsys
        Waker["task/src/waker.rs"]:::subsys
        YieldNow["task/src/yield_now.rs"]:::subsys
    end

    %% Layer 5: Device Drivers & Graphics
    subgraph "Layer 5: Drivers & Graphics"
        direction TB
        KeyboardDrv["keyboard/src/lib.rs"]:::driver
        GraphicsLib["graphics/src/lib.rs"]:::driver
        ConsoleMod["graphics/src/console/mod.rs"]:::driver
        FontBin["graphics/src/console/font8x16.bin"]:::driver
    end

    %% Layer 6: Capability & Util
    subgraph "Layer 6: Capability & Utility"
        direction TB
        CapLib["capability/src/lib.rs"]:::infra
        CapStore["capability/src/store.rs"]:::infra
        CapTypes["capability/src/types.rs"]:::infra
        UtilLib["util/src/lib.rs"]:::infra
        Panic["util/src/panic.rs"]:::infra
    end

    %% Build automation and docs
    Makefile["Makefile"]:::infra
    subgraph "Documentation"
        direction TB
        DocsBoot["docs/BOOT_PROCESS.md"]:::infra
        DocsHAL["docs/HAL_API.md"]:::infra
        DocsIRQ["docs/INTERRUPT_HANDLING.md"]:::infra
        DocsMem["docs/MEMORY_LAYOUT.md"]:::infra
        DocsGraf["docs/GRAPHICS_API.md"]:::infra
        DocsKern["docs/KERNEL_API.md"]:::infra
        DocsAdd["docs/ADD.md"]:::infra
        DocsRoad["docs/ROADMAP.md"]:::infra
    end

    %% External hardware
    CPU["CPU"]:::external
    RAM["RAM"]:::external
    PCI["PCI Bus"]:::external
    VGA["VGA Framebuffer"]:::external
    QEMU["QEMU/Hardware"]:::external

    %% Connections: Boot flow
    Bootloader -->|loads ELF & hands off| KernelMain
    KernelMain -->|setup GDT| GDT
    KernelMain -->|register syscalls| Syscall
    KernelMain -->|calls init| HALLib

    %% HAL init flow
    HALLib --> CPUInit
    HALLib --> IOPrims
    HALLib --> Serial
    HALLib --> Topology
    CPUInit --> CPU
    Serial --> QEMU

    %% Memory flow
    HALLib --> MemoryLib
    MemoryLib --> HeapAlloc
    MemoryLib --> RAM

    %% Interrupt flow
    HALLib --> IDTLib
    HALLib --> APICLib
    APICLib --> IOAPIC
    APICLib --> Timer
    IDTLib -->|exception handlers| CPU

    %% Task scheduler
    APICLib --> Executor
    IDTLib --> Executor
    Executor --> AsyncTask
    Executor --> ContextSwitch
    Executor --> Waker
    Executor --> YieldNow

    %% Drivers & devices
    KeyboardDrv -->|IRQ events| IDTLib
    IDTLib -->|wake task| Executor
    GraphicsLib --> ConsoleMod
    ConsoleMod --> FontBin
    GraphicsLib --> VGA

    %% Capability & util usage
    KernelMain --> CapLib
    KernelMain --> UtilLib
    CapLib --> CapStore
    CapLib --> CapTypes
    UtilLib --> Panic

    %% Build & docs
    Makefile --> KernelMain
    Makefile --> HALLib
    Makefile --> MemoryLib
    Makefile --> IDTLib
    Makefile --> APICLib
    Makefile --> TaskLib
    Makefile --> GraphicsLib
    Makefile --> KeyboardDrv
    Makefile --> CapLib
    Makefile --> UtilLib

    DocsBoot --> Bootloader
    DocsHAL --> HALLib
    DocsIRQ --> IDTLib
    DocsMem --> MemoryLib
    DocsGraf --> GraphicsLib
    DocsKern --> KernelMain
    DocsRoad --> Makefile

    %% Click Events
    click Bootloader "https://github.com/gitcomit8/serix/blob/main/limine.conf"
    click KernelMain "https://github.com/gitcomit8/serix/blob/main/kernel/src/main.rs"
    click GDT "https://github.com/gitcomit8/serix/blob/main/kernel/src/gdt.rs"
    click Syscall "https://github.com/gitcomit8/serix/blob/main/kernel/src/syscall.rs"
    click LinkerScript "https://github.com/gitcomit8/serix/blob/main/kernel/linker.ld"
    click HALLib "https://github.com/gitcomit8/serix/blob/main/hal/src/lib.rs"
    click CPUInit "https://github.com/gitcomit8/serix/blob/main/hal/src/cpu.rs"
    click IOPrims "https://github.com/gitcomit8/serix/blob/main/hal/src/io.rs"
    click Serial "https://github.com/gitcomit8/serix/blob/main/hal/src/serial.rs"
    click Topology "https://github.com/gitcomit8/serix/blob/main/hal/src/topology.rs"
    click IDTLib "https://github.com/gitcomit8/serix/blob/main/idt/src/lib.rs"
    click APICLib "https://github.com/gitcomit8/serix/blob/main/apic/src/lib.rs"
    click IOAPIC "https://github.com/gitcomit8/serix/blob/main/apic/src/ioapic.rs"
    click Timer "https://github.com/gitcomit8/serix/blob/main/apic/src/timer.rs"
    click MemoryLib "https://github.com/gitcomit8/serix/blob/main/memory/src/lib.rs"
    click HeapAlloc "https://github.com/gitcomit8/serix/blob/main/memory/src/heap.rs"
    click TaskLib "https://github.com/gitcomit8/serix/blob/main/task/src/lib.rs"
    click Executor "https://github.com/gitcomit8/serix/blob/main/task/src/executor.rs"
    click AsyncTask "https://github.com/gitcomit8/serix/blob/main/task/src/async_task.rs"
    click ContextSwitch "https://github.com/gitcomit8/serix/blob/main/task/src/context_switch.rs"
    click Waker "https://github.com/gitcomit8/serix/blob/main/task/src/waker.rs"
    click YieldNow "https://github.com/gitcomit8/serix/blob/main/task/src/yield_now.rs"
    click GraphicsLib "https://github.com/gitcomit8/serix/blob/main/graphics/src/lib.rs"
    click ConsoleMod "https://github.com/gitcomit8/serix/blob/main/graphics/src/console/mod.rs"
    click FontBin "https://github.com/gitcomit8/serix/blob/main/graphics/src/console/font8x16.bin"
    click KeyboardDrv "https://github.com/gitcomit8/serix/blob/main/keyboard/src/lib.rs"
    click CapLib "https://github.com/gitcomit8/serix/blob/main/capability/src/lib.rs"
    click CapStore "https://github.com/gitcomit8/serix/blob/main/capability/src/store.rs"
    click CapTypes "https://github.com/gitcomit8/serix/blob/main/capability/src/types.rs"
    click UtilLib "https://github.com/gitcomit8/serix/blob/main/util/src/lib.rs"
    click Panic "https://github.com/gitcomit8/serix/blob/main/util/src/panic.rs"
    click Makefile "https://github.com/gitcomit8/serix/tree/main/Makefile"
    click DocsBoot "https://github.com/gitcomit8/serix/blob/main/docs/BOOT_PROCESS.md"
    click DocsHAL "https://github.com/gitcomit8/serix/blob/main/docs/HAL_API.md"
    click DocsIRQ "https://github.com/gitcomit8/serix/blob/main/docs/INTERRUPT_HANDLING.md"
    click DocsMem "https://github.com/gitcomit8/serix/blob/main/docs/MEMORY_LAYOUT.md"
    click DocsGraf "https://github.com/gitcomit8/serix/blob/main/docs/GRAPHICS_API.md"
    click DocsKern "https://github.com/gitcomit8/serix/blob/main/docs/KERNEL_API.md"
    click DocsAdd "https://github.com/gitcomit8/serix/blob/main/docs/ADD.md"
    click DocsRoad "https://github.com/gitcomit8/serix/blob/main/docs/ROADMAP.md"

    %% Styles
    classDef boot fill:#cce5ff,stroke:#000,stroke-width:1px
    classDef kernel fill:#d4edda,stroke:#000,stroke-width:1px
    classDef subsys fill:#fff3cd,stroke:#000,stroke-width:1px
    classDef driver fill:#ffeeba,stroke:#000,stroke-width:1px
    classDef infra fill:#e2e3e5,stroke:#000,stroke-width:1px
    classDef external fill:#f8d7da,stroke:#000,stroke-width:1px
```
