# ashishyesale7/sage-os architecture

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

- Interactive diagram: https://gitdiagram.com/ashishyesale7/sage-os
- Repository: https://github.com/ashishyesale7/sage-os

## Overview

##### Project Type and Purpose
- SAGE OS is a bare-metal, multi-architecture operating system with an integrated AI subsystem.
- Purpose: Autonomously learn, adapt, and evolve on hardware (Raspberry Pi and x86) via an AI HAT+ accelerator and embedded machine learning.

##### File Structure
- Top-level directories:
- boot/        → Architecture-specific bootloaders (ARM, x86, RISC-V, multiboot)
- kernel/      → Core kernel in C/Assembly + AI subsystem in C (and Rust in prototype)
- drivers/     → Low-level hardware drivers: UART, I2C, SPI, VGA, AI HAT+
- scripts/     → Build, test, CI/CD, security scanning, ISO creation
- sage-sdk/    → SDK for writing modules/apps against SAGE OS syscalls and AI APIs
- prototype/, minimal/ → Early/reference implementations
- dist/, iso/  → Release artifacts (images, ISOs)
- Build and CI configs: Makefile, Dockerfiles, GitHub Actions workflows.

##### README for Additional Insights
- Layers: Bootloader → Kernel Core → AI Subsystem → Shell UI → Hardware
- Tech stack: ARM Assembly, C, Rust, Python, QEMU, Docker, CMake, TinyML
- Features: Multi-arch builds, containerized CI, CVE scanning, QEMU testing.

##### Main Components and Their Roles
a. Hardware Layer
- Raspberry Pi 3/4/5 (ARM) and x86 (i386, x86_64), AI HAT+ accelerator.
b. Bootloader Layer
- boot/*.S: Early assembly stages, multiboot entry, CPU initialization.
c. Kernel Core
- kernel/kernel.c, memory.c, shell.c, stdio.c
- Rust core in prototype (future evolution).
d. AI Subsystem
- kernel/ai/ai_subsystem.c/.h
- Communicates with AI HAT+ via SPI/I2C drivers.
e. Drivers
- drivers/*: UART, VGA, SPI, I2C, Serial, AI HAT+
- Hardware Abstraction Layer for Pi and x86.
f. Shell & CLI
- kernel/shell.c: Exposes commands (meminfo, ai info, reboot).
g. SDK & User Modules
- sage-sdk/: C and Python examples, headers, libraries, model builder, NAS trainer.
h. Build & Test Infrastructure
- scripts/, Dockerfiles, Makefile, GitHub workflows, QEMU runner.
i. Security & CI/CD
- CVE scan scripts, GitHub Actions for code quality, security, multi-arch builds.

##### Relationships and Data Flow
- Bootloader → Loads Kernel Core into memory → Initializes Drivers → Starts AI Subsystem → Launches Shell
- Shell commands invoke kernel services and AI APIs → Drivers mediate hardware access → AI Subsystem may trigger reconfiguration.
- Build scripts cross-compile per architecture and package images → Docker/GitHub CI runs builds, tests, security scans → Generates artifacts in dist/ and build-output/.

##### Architectural Patterns & Principles
- Layered Modular Architecture: Clear separation Boot → Kernel → Drivers → Subsystems → SDK.
- Hardware Abstraction: Single driver API for multiple architectures.
- Cross-Compilation & Containerization: Build once, deploy everywhere.
- Self-Adaptive AI Loop: Monitoring → Inference → Reconfiguration.

##### Detail
- Subsystem, its language (C, Assembly, Rust), and its build artifacts (ELF, IMG, ISO).
- Interactions with QEMU for emulation and Docker for containerized builds.
- Security scanning step between CI and release artifact generation.

## Diagram (Mermaid)

```mermaid
graph TB
    subgraph "Hardware Layer"
        Pi["Raspberry Pi (ARM)"]:::hardware
        X86["x86 (i386, x86_64)"]:::hardware
        AIHAT["AI HAT+ Accelerator"]:::ai
    end

    subgraph "Bootloader Layer"
        Boot["Bootloader (boot/*.S)"]:::bootcode
    end

    subgraph "Kernel Core"
        KC["Kernel Core (kernel/*.c, .h)"]:::code
        Mem["Memory Mgmt (kernel/memory.c)"]:::code
        Stdio["StdIO (kernel/stdio.c)"]:::code
        Utils["Utils (kernel/utils.c)"]:::code
        Types["Types (kernel/types.h)"]:::code
        Shell["Shell & CLI (kernel/shell.c)"]:::code
    end

    subgraph "Drivers & AI Subsystem"
        Drivers["Drivers (drivers/*)"]:::code
        AI["AI Subsystem (kernel/ai/*.c, .h)"]:::ai
    end

    subgraph "SDK & Tooling"
        SDK["SDK & User Modules (sage-sdk/)"]:::tool
        Build["Build & Cross-Compile (Makefile, Dockerfiles)"]:::tool
        Test["Test Infra (scripts/, .github/workflows/)"]:::tool
        Release["Release Artifacts (dist/, iso/)"]:::tool
    end

    subgraph "Minimal & Prototype"
        Minimal["Minimal (minimal/*)"]:::code
        Proto["Prototype (prototype/*)"]:::code
    end

    %% Control and Data Flow
    Pi -->|drives| Boot
    X86 -->|drives| Boot
    AIHAT -->|accelerated by| AI
    Boot -->|loads| KC
    KC -->|uses| Drivers
    KC -->|initializes| AI
    KC -->|launches| Shell
    Drivers -->|access| Pi
    Drivers -->|access| X86
    Drivers -->|communicates via| AIHAT
    Shell -->|invokes services| KC

    Build -->|cross-compiles| Boot
    Build -->|cross-compiles| KC
    Build -->|packages| Release
    Test -->|emulates in QEMU| Build
    Test -->|runs CI/CD| Build
    Test -->|triggers| Release

    SDK -->|uses syscalls & APIs| KC
    SDK -->|builds modules| KC

    Minimal -->|reference implementation| Boot
    Minimal -->|reference implementation| KC
    Proto -->|experimental| AI

    %% Click Events
    click Drivers "https://github.com/ashishyesale7/sage-os/tree/dev/drivers/"
    click Boot "https://github.com/ashishyesale7/sage-os/tree/dev/boot/"
    click KC "https://github.com/ashishyesale7/sage-os/tree/dev/kernel/"
    click AI "https://github.com/ashishyesale7/sage-os/tree/dev/kernel/ai/"
    click Shell "https://github.com/ashishyesale7/sage-os/blob/dev/kernel/shell.c"
    click SDK "https://github.com/ashishyesale7/sage-os/tree/dev/sage-sdk/"
    click Build "https://github.com/ashishyesale7/sage-os/tree/dev/Makefile"
    click Test "https://github.com/ashishyesale7/sage-os/tree/dev/.github/workflows/"
    click Release "https://github.com/ashishyesale7/sage-os/tree/dev/dist/"
    click Minimal "https://github.com/ashishyesale7/sage-os/tree/dev/minimal/"
    click Proto "https://github.com/ashishyesale7/sage-os/tree/dev/prototype/"

    %% Styles
    classDef hardware fill:#ccffcc,stroke:#333,stroke-width:1px
    classDef ai fill:#ccffcc,stroke:#333,stroke-width:1px
    classDef bootcode fill:#cce5ff,stroke:#333,stroke-width:1px
    classDef code fill:#e6f7ff,stroke:#333,stroke-width:1px
    classDef tool fill:#ffe5b4,stroke:#333,stroke-width:1px
```
