# nmc-techclub/sage-os architecture

> Architecture diagram of the GitHub repository nmc-techclub/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/nmc-techclub/sage-os
- Repository: https://github.com/nmc-techclub/sage-os

## Overview

##### Project type and purpose
- This is a bare-metal, self-evolving operating system (SAGE OS) for Raspberry Pi and other architectures.
- It combines kernel engineering, embedded systems, and AI/ML to detect hardware, compile platform-specific kernels/drivers, build images, boot, monitor, and evolve itself.

##### File structure
- Top-level directories:
- boot/           – Architecture-specific assembly bootloader
- kernel/         – Core kernel modules (memory, processes) in C
- drivers/        – Low-level hardware drivers (UART, etc.)
- sage-sdk/       – SDK for module development (includes C headers, Python examples, static libs, tools)
- scripts/        – Build and QEMU test scripts
- tests/          – Unit, integration, AI-behavior, security, update rollbacks
- docs/, README  – Vision, architecture, build/run instructions, theoretical foundations
- Configuration and build:
- Makefile, linker.ld, CMakeLists in sage-sdk
- Python scripts for license checking and AI prototyping

##### Key insights from README
- Workflow:
1. AI detects architecture/hardware
2. Generates kernel+drivers
3. Builds bootable image (.img/.iso/container)
4. Boots on real hardware or QEMU
5. Continuous monitoring (uptime, latency, etc.)
6. If stable → promote; if unstable → rollback
- Tech stack: ARM assembly, C, Python, GCC cross-compilers, QEMU, TinyML (TFLM/uTensor)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Host-side Tooling & CI
    subgraph "Host-side Tooling & CI"
        MAKE["Makefile"]:::tooling
        SCRIPTS["scripts/test_emulated.sh"]:::tooling
        TC["sage-sdk/toolchains/"]:::tooling
        QEMU_TEST["sage-sdk/tools/qemu-test"]:::tooling
        CMAKE_SDK["sage-sdk/CMakeLists.txt"]:::tooling
        SDK_INC["sage-sdk/include/"]:::tooling
        SDK_LIB["sage-sdk/lib/"]:::tooling
        SDK_EX["sage-sdk/examples/"]:::tooling
        AZR["sage-sdk/tools/azr-model-builder"]:::tooling
        NAS["sage-sdk/tools/nas-train"]:::tooling
        PACKAGE_TOOL["sage-sdk/tools/sage-package"]:::tooling
        GITHUB[".github/workflows/"]:::ci
        TEST_CORE["tests/core_tests/"]:::ci
        TEST_INT["tests/integration_tests/"]:::ci
        TEST_AI["tests/ai_tests/"]:::ci
        TEST_SEC["tests/security_tests/"]:::ci
        TEST_UP["tests/update_tests/"]:::ci
    end

    %% Cross-Compilation & Image Build
    subgraph "Cross-Compilation & Image Build"
        CC["Cross-Compiler"]:::tooling
        IMG["Bootable Image (.img/.iso)"]:::storage
    end

    %% Emulation
    subgraph "Emulation"
        QEMU["QEMU Emulator"]:::external
    end

    %% Hardware Target & Runtime
    subgraph "Hardware Target"
        HW["Hardware (ARM/RPi4)"]:::hardware
        BL["Bootloader"]:::runtime
        KERNEL["Kernel Core"]:::runtime
        DRV["Driver Subsystem"]:::runtime
        MON["Monitoring Service"]:::runtime
        AI["AI Agent Service"]:::runtime
    end

    %% Workflow Connections
    MAKE & SCRIPTS & CMAKE_SDK & TC & QEMU_TEST & SDK_INC & SDK_LIB & SDK_EX & AZR & NAS & PACKAGE_TOOL --> CC
    CC --> IMG
    IMG --> QEMU
    IMG --> HW
    QEMU --> BL
    HW --> BL --> KERNEL --> DRV --> HW
    KERNEL <-->|"telemetry data"| MON
    MON -->|"anomaly signal"| AI
    AI -->|"rebuild/configure"| PACKAGE_TOOL

    %% Kernel-AI Interaction
    KERNEL <-->|"config decisions"| AI

    %% CI to Tests
    GITHUB --> TEST_CORE & TEST_INT & TEST_AI & TEST_SEC & TEST_UP

    %% SDK Users Path
    SDK_EX -->|"use APIs"| KERNEL

    %% Click Events
    click MAKE "https://github.com/nmc-techclub/sage-os/tree/main/Makefile"
    click SCRIPTS "https://github.com/nmc-techclub/sage-os/blob/main/scripts/test_emulated.sh"
    click TC "https://github.com/nmc-techclub/sage-os/tree/main/sage-sdk/toolchains/"
    click QEMU_TEST "https://github.com/nmc-techclub/sage-os/tree/main/sage-sdk/tools/qemu-test"
    click CMAKE_SDK "https://github.com/nmc-techclub/sage-os/blob/main/sage-sdk/CMakeLists.txt"
    click SDK_INC "https://github.com/nmc-techclub/sage-os/tree/main/sage-sdk/include/"
    click SDK_LIB "https://github.com/nmc-techclub/sage-os/tree/main/sage-sdk/lib/"
    click SDK_EX "https://github.com/nmc-techclub/sage-os/tree/main/sage-sdk/examples/"
    click AZR "https://github.com/nmc-techclub/sage-os/tree/main/sage-sdk/tools/azr-model-builder"
    click NAS "https://github.com/nmc-techclub/sage-os/tree/main/sage-sdk/tools/nas-train"
    click PACKAGE_TOOL "https://github.com/nmc-techclub/sage-os/tree/main/sage-sdk/tools/sage-package"
    click GITHUB "https://github.com/nmc-techclub/sage-os/tree/main/.github/workflows/"
    click TEST_CORE "https://github.com/nmc-techclub/sage-os/tree/main/tests/core_tests/"
    click TEST_INT "https://github.com/nmc-techclub/sage-os/tree/main/tests/integration_tests/"
    click TEST_AI "https://github.com/nmc-techclub/sage-os/tree/main/tests/ai_tests/"
    click TEST_SEC "https://github.com/nmc-techclub/sage-os/tree/main/tests/security_tests/"
    click TEST_UP "https://github.com/nmc-techclub/sage-os/tree/main/tests/update_tests/"
    click BL "https://github.com/nmc-techclub/sage-os/blob/main/boot/boot.S"
    click BL "https://github.com/nmc-techclub/sage-os/blob/main/linker.ld"
    click KERNEL "https://github.com/nmc-techclub/sage-os/blob/main/kernel/kernel.c"
    click KERNEL "https://github.com/nmc-techclub/sage-os/blob/main/kernel/kernel.h"
    click DRV "https://github.com/nmc-techclub/sage-os/blob/main/drivers/uart.c"
    click DRV "https://github.com/nmc-techclub/sage-os/blob/main/drivers/uart.h"
    click AI "https://github.com/nmc-techclub/sage-os/blob/main/sage-sdk/include/aihat.h"
    click AI "https://github.com/nmc-techclub/sage-os/blob/main/sage-sdk/lib/libaihat.a"
    click AZR "https://github.com/nmc-techclub/sage-os/tree/main/sage-sdk/tools/azr-model-builder"
    click NAS "https://github.com/nmc-techclub/sage-os/tree/main/sage-sdk/tools/nas-train"

    %% Styling
    classDef hardware fill:#ADD8E6,stroke:#000;
    classDef runtime fill:#90EE90,stroke:#000;
    classDef tooling fill:#FFA500,stroke:#000;
    classDef ci fill:#D3D3D3,stroke:#000;
    classDef external fill:#F0F0F0,stroke:#000;
    classDef storage fill:#FFFFE0,stroke:#000;
```
