# zipleix/alpha-os architecture

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

- Interactive diagram: https://gitdiagram.com/zipleix/alpha-os
- Repository: https://github.com/zipleix/alpha-os

## Overview

##### Main Components
- Bootloader: Represented by the contents in src/boot (boot.asm) which initializes hardware and loads the kernel.
- Kernel Core: Comprised of src/kernel (kernel.asm, kernel.c, kernel.h) where the main control logic resides.
- Configuration: Highlight src/config.h, which holds configuration settings used across the kernel.
- Disk Management: Encapsulate the disk I/O logic from src/disk.
- File System: Include the file operations from src/fs; note the FAT implementation in src/fs/fat.
- Memory Management: Detail components from src/memory (heap, paging) that handle dynamic allocation, paging, and general memory tasks.
- I/O Operations: From src/io, illustrate routines for interacting with hardware I/O.
- System Call Handling: Capture the functionality in src/isr80h, which implements system call entry points (IO, memory, process, and misc routines).
- Task Management: Represent the process and task management elements found in src/task.
- Utilities: Denote additional fundamental services such as string handling (src/string) and status codes (src/status.h).
- Linker Script: Include the linker scripts (src/linker.ld, programs/*/linker.ld) to show the build and linking process.
- User-space Programs (Optional): The “programs” directory (with subdirectories like “shell”, “stdlib”, and “blank”) contains user-space programs and libraries that run on or interact with the kernel. Although secondary in purpose, they complete the ecosystem by demonstrating how applications are built to run on Alpha OS.

##### Relationships and Interactions
- From the Kernel Core, illustrate internal communication:
- Configuration file (src/config.h) as a component that feeds into several modules (kernel, memory, and I/O) to emphasize its global relevance.

##### Architectural Patterns and Design Principles
- Then, indicate how higher-level functionalities (file system, task management, and user processes) are built on top of these layers.
- Modularity since each directory (e.g., src/fs, src/memory) represents a module with clear responsibilities.
- Mention the separation of concerns, especially between hardware initialization (bootloader, GDT/IDT) and system services (kernel, memory, task scheduling).

##### Technologies, Frameworks, and Tools
- That GCC cross-compilation, Makefiles, and build scripts (Makefile, build.sh) are integral to the compilation and setup process.
- Mention that QEMU is used for emulation/testing. You might show an external “Emulator Environment (QEMU)” block that interacts with the compiled kernel image.

##### Final Touches
- Every component is connected logically, and highlight any feedback loops (e.g., hardware interrupts looping into IDT routines).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Boot Process Layer
    subgraph "Boot Process Layer"
        BL["Bootloader"]:::boot
    end

    %% Kernel Initialization and Modules
    subgraph "Kernel Initialization and Modules"
        KC["Kernel Core"]:::core
        subgraph "Kernel Modules"
            MEM["Memory Management"]:::mem
            DISK["Disk Management"]:::disk
            FS["File System"]:::filesystem
            GDT["GDT"]:::lowlevel
            IDT["IDT"]:::lowlevel
            IOOP["I/O Operations"]:::lowlevel
            TASK["Task Management"]:::sys
            SCALL["System Call Handling"]:::sys
        end
    end

    %% Configuration and Utilities
    subgraph "Configuration & Utilities"
        CFG["Configuration"]:::config
        UTIL["Utilities"]:::util
        LINKER["Linker Scripts"]:::util
    end

    %% User Space
    subgraph "User Space"
        UP["User Programs"]:::user
    end

    %% External Emulator
    EMU["Emulator (QEMU)"]:::external

    %% Connections
    BL -->|"loads"| KC
    KC -->|"init_memory"| MEM
    KC -->|"disk_access"| DISK
    KC -->|"file_sys"| FS
    KC -->|"setup_GDT"| GDT
    KC -->|"setup_IDT"| IDT
    KC -->|"init_IO"| IOOP
    KC -->|"task_sched"| TASK
    KC -->|"sys_call"| SCALL

    CFG -->|"config"| KC
    CFG -->|"config"| MEM
    CFG -->|"config"| IOOP

    UTIL -->|"build"| KC
    LINKER -->|"link"| KC

    SCALL -->|"syscall"| UP

    EMU -->|"emulate"| BL
    KC -->|"deploy"| EMU

    %% Click Events
    click BL "https://github.com/zipleix/alpha-os/blob/master/src/boot/boot.asm"
    click KC "https://github.com/zipleix/alpha-os/blob/master/src/kernel/kernel.asm"
    click CFG "https://github.com/zipleix/alpha-os/blob/master/src/config.h"
    click DISK "https://github.com/zipleix/alpha-os/tree/master/src/disk"
    click FS "https://github.com/zipleix/alpha-os/tree/master/src/fs"
    click MEM "https://github.com/zipleix/alpha-os/tree/master/src/memory"
    click GDT "https://github.com/zipleix/alpha-os/tree/master/src/gdt"
    click IDT "https://github.com/zipleix/alpha-os/tree/master/src/idt"
    click IOOP "https://github.com/zipleix/alpha-os/tree/master/src/io"
    click SCALL "https://github.com/zipleix/alpha-os/tree/master/src/isr80h"
    click TASK "https://github.com/zipleix/alpha-os/tree/master/src/task"
    click UTIL "https://github.com/zipleix/alpha-os/tree/master/src/string"
    click LINKER "https://github.com/zipleix/alpha-os/blob/master/src/linker.ld"
    click UP "https://github.com/zipleix/alpha-os/tree/master/programs"

    %% Styles
    classDef boot fill:#add8e6,stroke:#000,stroke-width:2px;
    classDef core fill:#90ee90,stroke:#000,stroke-width:2px;
    classDef config fill:#ffff99,stroke:#000,stroke-width:2px;
    classDef mem fill:#ffb6c1,stroke:#000,stroke-width:2px;
    classDef disk fill:#ffdead,stroke:#000,stroke-width:2px;
    classDef filesystem fill:#dda0dd,stroke:#000,stroke-width:2px;
    classDef lowlevel fill:#d3d3d3,stroke:#000,stroke-width:2px;
    classDef sys fill:#ffcccb,stroke:#000,stroke-width:2px;
    classDef util fill:#f0e68c,stroke:#000,stroke-width:2px;
    classDef user fill:#afeeee,stroke:#000,stroke-width:2px;
    classDef external fill:#e6e6fa,stroke:#000,stroke-width:2px;
```
