# hycheng15/yalnix architecture

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

- Interactive diagram: https://gitdiagram.com/hycheng15/yalnix
- Repository: https://github.com/hycheng15/yalnix

## Overview

##### Project type and purpose
- This is an educational, monolithic operating system project (“Yalnix”) composed of three modules:
– Device-Driver: hardware and terminal driver code in C
– Yalnix-OS-Kernel: core kernel with process control, memory, syscalls, traps, scheduler
– Yalnix-File-System: user‐level file system with caching and I/O library
- Purpose is to teach OS concepts: driver interface, kernel internals, file system layering.

##### File structure
- Top level: three sibling directories, each with a Makefile, source, headers, tests.
- Device-Driver: montty.c + include/ + tests/ → hardware abstraction layer for terminals & threads
- Yalnix-OS-Kernel: init.c, memory.c, syscalls.c, trap_handler.c, pcb.{c,h}, globals.c → kernel core
- Yalnix-File-System: yfs.c, yfscall.c, plus subdirectories cache/, fs/, iolib/ → modular FS
- All three modules link into a single OS image; tests simulate user‐level programs exercising each module.

##### README for additional insights
- Confirms three main components and how they integrate
- Each module has its own build instructions and tests
- No external services—everything runs on bare metal or simulator

- Hardware (CPU, Memory, Disk, Terminal device)
- Device Driver module (montty, hardware.h, terminals.h, threads.h)
- OS Kernel (init, idle, load, globals, memory manager, PCB manager, trap handler, syscalls)
- File System module (yfs, yfscall, cache, fs core, iolib)
- User‐level processes/tests (shell, test programs)
- User processes → syscall API → Kernel
- Kernel → device driver → hardware registers/interrupts
- Kernel → file system calls → FS module → cache layer → disk I/O
- Hardware interrupts → trap handler in kernel → thread scheduler
c. Architectural patterns and principles:
- Layering: Hardware → Driver → Kernel → File System → User space
- Modular separation: each major concern in its own directory/module
- Single address space (educational OS), monolithic kernel
d. Key technologies/frameworks:
- Language: C
- Build: Makefiles & shell scripts
- Testing: C test suites in each module

##### Final advice
- Every module as its own entity, then connect them according to call flow and data flow
- It reflects the three‐part structure of Device-Driver, OS-Kernel, File-System and their integration

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Hardware Layer
    subgraph "Hardware" 
        direction TB
        CPU(("CPU")):::hardware
        Memory(("Memory")):::hardware
        Disk(("Disk")):::hardware
        TerminalDevice(("Terminal Device")):::hardware
    end

    %% Device Driver Module
    subgraph "Device Driver Module" 
        direction TB
        Montty["montty.c"]:::driver
        HardwareH["hardware.h"]:::driver
        TerminalsH["terminals.h"]:::driver
        ThreadsH["threads.h"]:::driver
        DriverTests["tests/"]:::driver
    end

    %% OS Kernel Core
    subgraph "Yalnix-OS-Kernel" 
        direction TB
        InitC["init.c"]:::kernel
        IdleC["idle.c"]:::kernel
        LoadC["load.c"]:::kernel
        YalnixC["yalnix.c"]:::kernel
        MemoryC["memory.c"]:::kernel
        PCBManager["pcb.c/.h"]:::kernel
        GlobalsC["globals.c"]:::kernel
        SyscallsC["syscalls.c"]:::kernel
        TrapHandlerC["trap_handler.c"]:::kernel
        SecondC["second.c"]:::kernel
        KernelTests["tests/"]:::kernel
    end

    %% File System Module
    subgraph "Yalnix-File-System"
        direction TB
        YFS["yfs.c"]:::fs
        YFSCall["yfscall.c"]:::fs
        GlobalFS["global.h"]:::fs
        subgraph "Cache Layer"
            direction TB
            CacheC["cache.c"]:::fs
            CacheH["cache.h"]:::fs
        end
        subgraph "Core FS Operations"
            direction TB
            PathC["path.c"]:::fs
            PathH["path.h"]:::fs
        end
        subgraph "I/O Library"
            direction TB
            IOLibC["iolib.c"]:::fs
            IOLibH["iolib.h"]:::fs
        end
        FSTests["tests/"]:::fs
    end

    %% User Processes Layer
    subgraph "User-Level Processes / Tests"
        direction TB
        Shell["Shell / Test Programs"]:::user
    end

    %% Relationships
    Shell -->|"read()/write() syscall"| SyscallsC
    Shell -->|"exec()/fork() syscall"| SyscallsC

    SyscallsC -->|"dispatch"| YalnixC
    YalnixC -->|"memory alloc/free"| MemoryC
    YalnixC -->|"manage PCB"| PCBManager
    TrapHandlerC -->|"handle interrupt"| YalnixC
    CPU -->|"hardware interrupt"| TrapHandlerC
    TrapHandlerC -->|"invoke scheduler"| IdleC

    YalnixC -->|"device I/O calls"| Montty
    Montty -->|"access registers"| TerminalDevice
    Montty -->|"use abstractions"| HardwareH
    Montty -->|"interface definitions"| TerminalsH
    Montty -->|"thread support APIs"| ThreadsH

    SyscallsC -->|"file operations"| YFSCall
    YFSCall -->|"proxy to FS core"| YFS
    YFS -->|"use globals"| GlobalFS
    YFS -->|"cache read/write"| CacheC
    CacheC -->|"update metadata"| CacheH
    YFS -->|"path handling"| PathC
    PathC -->|"definitions"| PathH
    YFS -->|"IO support"| IOLibC
    IOLibC -->|"headers"| IOLibH
    YFS -->|"block I/O"| Disk

    %% Click Events
    click Montty "https://github.com/hycheng15/yalnix/blob/main/Device-Driver/montty.c"
    click HardwareH "https://github.com/hycheng15/yalnix/blob/main/Device-Driver/include/hardware.h"
    click TerminalsH "https://github.com/hycheng15/yalnix/blob/main/Device-Driver/include/terminals.h"
    click ThreadsH "https://github.com/hycheng15/yalnix/blob/main/Device-Driver/include/threads.h"
    click DriverTests "https://github.com/hycheng15/yalnix/tree/main/Device-Driver/tests/"
    click InitC "https://github.com/hycheng15/yalnix/blob/main/Yalnix-OS-Kernel/init.c"
    click IdleC "https://github.com/hycheng15/yalnix/blob/main/Yalnix-OS-Kernel/idle.c"
    click LoadC "https://github.com/hycheng15/yalnix/blob/main/Yalnix-OS-Kernel/load.c"
    click YalnixC "https://github.com/hycheng15/yalnix/blob/main/Yalnix-OS-Kernel/yalnix.c"
    click MemoryC "https://github.com/hycheng15/yalnix/blob/main/Yalnix-OS-Kernel/memory.c"
    click PCBManager "https://github.com/hycheng15/yalnix/blob/main/Yalnix-OS-Kernel/pcb.c"
    click GlobalsC "https://github.com/hycheng15/yalnix/blob/main/Yalnix-OS-Kernel/globals.c"
    click SyscallsC "https://github.com/hycheng15/yalnix/blob/main/Yalnix-OS-Kernel/syscalls.c"
    click TrapHandlerC "https://github.com/hycheng15/yalnix/blob/main/Yalnix-OS-Kernel/trap_handler.c"
    click SecondC "https://github.com/hycheng15/yalnix/blob/main/Yalnix-OS-Kernel/second.c"
    click KernelTests "https://github.com/hycheng15/yalnix/tree/main/Yalnix-OS-Kernel/tests/"
    click YFS "https://github.com/hycheng15/yalnix/blob/main/Yalnix-File-System/yfs.c"
    click YFSCall "https://github.com/hycheng15/yalnix/blob/main/Yalnix-File-System/yfscall.c"
    click GlobalFS "https://github.com/hycheng15/yalnix/blob/main/Yalnix-File-System/global.h"
    click CacheC "https://github.com/hycheng15/yalnix/blob/main/Yalnix-File-System/cache/cache.c"
    click CacheH "https://github.com/hycheng15/yalnix/blob/main/Yalnix-File-System/cache/cache.h"
    click PathC "https://github.com/hycheng15/yalnix/blob/main/Yalnix-File-System/fs/path.c"
    click PathH "https://github.com/hycheng15/yalnix/blob/main/Yalnix-File-System/fs/path.h"
    click IOLibC "https://github.com/hycheng15/yalnix/blob/main/Yalnix-File-System/iolib/iolib.c"
    click IOLibH "https://github.com/hycheng15/yalnix/blob/main/Yalnix-File-System/iolib/iolib.h"
    click FSTests "https://github.com/hycheng15/yalnix/tree/main/Yalnix-File-System/tests/"

    %% Styles
    classDef hardware fill:#f2f2f2,stroke:#666,stroke-width:1px
    classDef driver fill:#cce5ff,stroke:#004085,stroke-width:1px
    classDef kernel fill:#d4edda,stroke:#155724,stroke-width:1px
    classDef fs fill:#fff3cd,stroke:#856404,stroke-width:1px
    classDef user fill:#f8d7da,stroke:#721c24,stroke-width:1px,stroke-dasharray: 5 5
```
