# pezfisk/invos architecture

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

- Interactive diagram: https://gitdiagram.com/pezfisk/invos
- Repository: https://github.com/pezfisk/invos

## Overview

##### Project type and purpose
- This is a low-level OS kernel (“InvOS”) written in Rust, following Philipp Oppermann’s blog tutorial. Its goal is to produce a minimal executable that boots on x86_64 hardware or QEMU, sets up the CPU (GDT, interrupt handling), and provides simple I/O (VGA text buffer, serial port).

##### File structure
- Top-level Rust/Cargo files and toolchain configuration (.cargo/, Cargo.toml, rust-toolchain) define a no_std kernel crate with custom target spec (x86_64-inv.json).
- src/ holds kernel code split into logical modules:
- main.rs – entry point (`_start`) and high-level init
- gdt.rs – Global Descriptor Table setup
- interrupts.rs – Interrupt Descriptor Table and handlers
- serial.rs – serial port driver interface
- vga_buffer.rs – VGA text buffer driver
- lib.rs – crate root (public exports, panic handler)
- tests/ contains integration tests that run the compiled kernel in QEMU and verify behavior (boot, panic conditions, stack overflow).

##### README
- Confirms that InvOS strictly follows the tutorial architecture: a bare-metal kernel with CPU initialization, minimal drivers, tests via QEMU. No mention of extra services or layers beyond the kernel itself.

##### Final advice
- Be exhaustive: break the kernel into as many logical sub-systems as you have modules.
- Both control flow (initialization sequence) and data flow (how output reaches VGA/serial).
- Use layering (hardware at bottom, kernel modules in the middle, tests/tools on the side) so it’s immediately clear where each piece lives and how they interact.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External Components
    Bootloader["Bootloader / QEMU"]:::external
    Toolchain["Cross-Compilation Toolchain"]:::external

    %% Kernel Layers
    subgraph "Kernel Entry"
        Entry["_start / main.rs"]:::entry
    end

    subgraph "CPU Initialization" 
        GDT["GDT Module"]:::cpu
        IDT["IDT & Interrupt Handlers"]:::cpu
    end

    subgraph "Device Drivers"
        VGA["VGA Text Buffer Driver"]:::driver
        Serial["Serial Port Driver"]:::driver
    end

    Lib["Crate Root & Panic Handler"]:::infrastructure

    %% Test Harness
    subgraph "Test Harness (QEMU)"
        BasicBoot["basic_boot.rs"]:::test
        ShouldPanic["should_panic.rs"]:::test
        StackOverflow["stack_overflow.rs"]:::test
    end

    %% Control Flow
    Bootloader -->|boots| Entry
    Entry -->|initializes| GDT
    GDT -->|sets up| IDT
    IDT -->|enables interrupts| Lib
    Lib -->|provides panic handler| Entry

    %% Data Flow to Drivers
    Entry -->|writes to| VGA
    Entry -->|writes to| Serial
    IDT -->|dispatches exceptions| Entry

    %% Toolchain builds kernel
    Toolchain -->|builds| Entry

    %% Test harness runs kernel via QEMU
    BasicBoot -->|launches QEMU| Bootloader
    ShouldPanic -->|launches QEMU| Bootloader
    StackOverflow -->|launches QEMU| Bootloader

    %% Click Events
    click Entry "https://github.com/pezfisk/invos/blob/main/src/main.rs"
    click GDT "https://github.com/pezfisk/invos/blob/main/src/gdt.rs"
    click IDT "https://github.com/pezfisk/invos/blob/main/src/interrupts.rs"
    click Serial "https://github.com/pezfisk/invos/blob/main/src/serial.rs"
    click VGA "https://github.com/pezfisk/invos/blob/main/src/vga_buffer.rs"
    click Lib "https://github.com/pezfisk/invos/blob/main/src/lib.rs"
    click Toolchain "https://github.com/pezfisk/invos/blob/main/Cargo.toml"
    click Toolchain "https://github.com/pezfisk/invos/blob/main/.cargo/config.toml"
    click Toolchain "https://github.com/pezfisk/invos/tree/main/rust-toolchain"
    click Toolchain "https://github.com/pezfisk/invos/blob/main/x86_64-inv.json"
    click BasicBoot "https://github.com/pezfisk/invos/blob/main/tests/basic_boot.rs"
    click ShouldPanic "https://github.com/pezfisk/invos/blob/main/tests/should_panic.rs"
    click StackOverflow "https://github.com/pezfisk/invos/blob/main/tests/stack_overflow.rs"

    %% Styles
    classDef external fill:#f9f,stroke:#333,stroke-width:2px
    classDef entry fill:#bbf,stroke:#333,stroke-width:2px
    classDef cpu fill:#fbf,stroke:#333,stroke-width:2px
    classDef driver fill:#bfb,stroke:#333,stroke-width:2px
    classDef infrastructure fill:#ffb,stroke:#333,stroke-width:2px
    classDef test fill:#fbb,stroke:#333,stroke-width:2px
```
