# sanufar/karkinos architecture

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

- Interactive diagram: https://gitdiagram.com/sanufar/karkinos
- Repository: https://github.com/sanufar/karkinos

## Overview

##### Project type and purpose
- This is a minimal operating‐system kernel written in Rust, with support for BIOS and UEFI boot (via QEMU targets) plus an associated host‐side testing harness.
- Its purpose is to compile a `kernel` library/crate, link it into bootable images, and run it under QEMU (and to run unit tests in “kernel mode” where possible).

##### File structure
- Top-level files and tools:
- Cargo.toml, rust-toolchain.toml, .cargo/config.toml → define Rust toolchain, dependencies, sccache setup
- build.rs, Makefile, test.sh → orchestrate custom build steps, caching, QEMU invocation
- src/bin/*.rs → host‐side binaries to launch QEMU with BIOS or UEFI payloads
- src/main.rs → default host binary (e.g., convenience CLI)
- kernel/ → the actual kernel crate
– src/lib.rs, src/main.rs → kernel entry point and library API
– framebuffer.rs, gdt.rs, idt.rs, interrupts.rs, logger.rs → hardware setup & HAL layers
– src/tests/ → in-kernel unit tests (math.rs, etc.)

##### README for additional insights
- Project name: “karkínos” (‘crab’ in Greek)
- Notes mention sccache usage and a TODO in the build script for Homebrew paths

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Build Environment
    subgraph "Build Environment"
        direction TB
        RustToolchain["rust-toolchain.toml"]:::build
        CargoConfig[".cargo/config.toml"]:::build
        CargoManifest["Cargo.toml"]:::build
        BuildScript["build.rs"]:::build
        Makefile["Makefile"]:::build
        TestScript["test.sh"]:::build
    end

    %% Kernel Crate
    subgraph "Kernel Crate"
        direction TB
        KernelManifest["kernel/Cargo.toml"]:::kernel
        KernelLib["kernel/src/lib.rs"]:::kernel
        KernelEntry["kernel/src/main.rs"]:::kernel
        subgraph "HAL Modules"
            direction TB
            Framebuffer["kernel/src/framebuffer.rs"]:::kernel
            GDT["kernel/src/gdt.rs"]:::kernel
            IDT["kernel/src/idt.rs"]:::kernel
            Interrupts["kernel/src/interrupts.rs"]:::kernel
            Logger["kernel/src/logger.rs"]:::kernel
        end
        subgraph "In-Kernel Tests"
            direction TB
            TestsMod["kernel/src/tests/mod.rs"]:::kernel
            MathTest["kernel/src/tests/math.rs"]:::kernel
        end
    end

    %% Host-Side Binaries
    subgraph "Host-Side Binaries"
        direction TB
        HostCLI["src/main.rs"]:::hostbin
        BIOSLauncher["src/bin/qemu-bios.rs"]:::hostbin
        UEFILauncher["src/bin/qemu-uefi.rs"]:::hostbin
        TestRunner["src/bin/kernel-test.rs"]:::hostbin
    end

    %% Host OS / Filesystem
    subgraph "Host OS / Filesystem"
        direction TB
        SccacheCache["sccache cache store"]:::storage
        CargoRegistry["Cargo registry"]:::storage
    end

    %% Emulator / Runtime Platform
    subgraph "Runtime Platform"
        direction TB
        QEMU["QEMU Emulator"]:::emulator
        VirtualHW["Virtual Hardware\n(CPU, Memory, VGA)"]:::emulator
    end

    %% Build flows
    RustToolchain -->|"configured by"| CargoManifest
    CargoConfig --> CargoManifest
    CargoManifest -->|"build scripts"| BuildScript
    BuildScript -->|"orchestrates"| KernelLib
    Makefile --> KernelLib
    TestScript --> TestRunner

    %% Host Tools consume Kernel Crate
    KernelLib -->|"link → binary"| HostCLI
    KernelEntry --> HostCLI
    KernelManifest --> HostCLI

    %% Host-Side to Emulator
    HostCLI -->|"invoke QEMU"| QEMU
    BIOSLauncher -->|"launch BIOS image"| QEMU
    UEFILauncher -->|"launch UEFI image"| QEMU
    TestRunner -.->|"run tests"| QEMU

    %% Emulator loads kernel
    QEMU -->|"loads bootable image"| KernelEntry
    QEMU --> VirtualHW

    %% Kernel Initialization
    KernelEntry -->|"init GDT"| GDT
    KernelEntry -->|"init IDT"| IDT
    KernelEntry -->|"init interrupts"| Interrupts
    KernelEntry -->|"init framebuffer"| Framebuffer
    KernelEntry -->|"init logger"| Logger

    %% Hardware interactions
    Framebuffer -->|"render"| VirtualHW
    Logger -->|"output to serial/VGA"| VirtualHW

    %% Tests flow back
    VirtualHW -.->|"test results"| TestRunner

    %% Host OS storage
    CargoConfig --> SccacheCache
    CargoManifest --> CargoRegistry

    %% Click events
    click RustToolchain "https://github.com/sanufar/karkinos/blob/main/rust-toolchain.toml"
    click CargoConfig "https://github.com/sanufar/karkinos/blob/main/.cargo/config.toml"
    click CargoManifest "https://github.com/sanufar/karkinos/blob/main/Cargo.toml"
    click BuildScript "https://github.com/sanufar/karkinos/blob/main/build.rs"
    click Makefile "https://github.com/sanufar/karkinos/tree/main/Makefile"
    click TestScript "https://github.com/sanufar/karkinos/blob/main/test.sh"
    click KernelManifest "https://github.com/sanufar/karkinos/blob/main/kernel/Cargo.toml"
    click KernelLib "https://github.com/sanufar/karkinos/blob/main/kernel/src/lib.rs"
    click KernelEntry "https://github.com/sanufar/karkinos/blob/main/kernel/src/main.rs"
    click Framebuffer "https://github.com/sanufar/karkinos/blob/main/kernel/src/framebuffer.rs"
    click GDT "https://github.com/sanufar/karkinos/blob/main/kernel/src/gdt.rs"
    click IDT "https://github.com/sanufar/karkinos/blob/main/kernel/src/idt.rs"
    click Interrupts "https://github.com/sanufar/karkinos/blob/main/kernel/src/interrupts.rs"
    click Logger "https://github.com/sanufar/karkinos/blob/main/kernel/src/logger.rs"
    click TestsMod "https://github.com/sanufar/karkinos/blob/main/kernel/src/tests/mod.rs"
    click MathTest "https://github.com/sanufar/karkinos/blob/main/kernel/src/tests/math.rs"
    click HostCLI "https://github.com/sanufar/karkinos/blob/main/src/main.rs"
    click BIOSLauncher "https://github.com/sanufar/karkinos/blob/main/src/bin/qemu-bios.rs"
    click UEFILauncher "https://github.com/sanufar/karkinos/blob/main/src/bin/qemu-uefi.rs"
    click TestRunner "https://github.com/sanufar/karkinos/blob/main/src/bin/kernel-test.rs"

    %% Styles
    classDef build fill:#ccffcc,stroke:#333,stroke-width:1px
    classDef kernel fill:#ccccff,stroke:#333,stroke-width:1px
    classDef hostbin fill:#ccffcc,stroke:#333,stroke-width:1px
    classDef storage fill:#fffee0,stroke:#333,stroke-width:1px,stroke-dasharray: 5 5
    classDef emulator fill:#ffcc99,stroke:#333,stroke-width:1px
```
