# ccleonos/leonos architecture

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

- Interactive diagram: https://gitdiagram.com/ccleonos/leonos
- Repository: https://github.com/ccleonos/leonos

## Overview

##### Project type and purpose
- LeonOS is not a typical web or mobile app. It’s a Lua-based operating system image and installer for the ComputerCraft mod in Minecraft.
- Purpose: provide a drop-in “BIOS” (ROM) and standard suite of shells, APIs, utilities, and an installer/updater for in-game computers.

##### File structure
Top-level:
- installer.lua – fetches and writes the OS image
- unbios.lua – minimal bootloader stub to chain-load LeonOS
- updater.lua – in-game updater for the installed OS
- pack.mcmeta – Minecraft resource-pack metadata
Config & CI:
- .github/workflows/release.yml – automates releases
- .trae/rules – project-specific code/style rules
- .VSCodeCounter – metrics history (editor plugin artifacts)
Core payload under data/computercraft/lua:
- bios.lua – main ROM startup code
- packages/… – example and installed Lua packages for users
- rom/apis/… – exported API libraries (fs, disk, http, rednet, etc.)
- rom/completions/… – shell completion specs
- rom/editors/… – in-game editors
- rom/modules/… – Lua modules for builtin commands and libraries
- rom/programs/… – user-facing shell programs (ls, copy, edit, turtle, etc.)
- rom/startup/… – startup sequence scripts (00_fs.lua → 90_settings.lua)
- update.lua – orchestrates ROM updates

##### README for additional insights
- Describes how to bootstrap installation via `wget run https://…/installer.lua`.
- Includes LeonCore’s BLC open-source license.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Interaction
    User["User (In-Game Shell)"]:::runtime
    click User "https://github.com/ccleonos/leonos/blob/main/data/computercraft/lua/bios.lua"

    %% Installer Stage
    Installer["Installer (installer.lua)"]:::installer
    click Installer "https://github.com/ccleonos/leonos/blob/main/installer.lua"
    User -->|"run installer.lua"| Installer
    Installer -->|"fetch ROM tarball"| GitHub
    Installer -->|"write unbios.lua, ROM folder, pack.mcmeta"| LocalFS

    %% External Services & Config
    GitHub["GitHub (Raw Assets & Releases)"]:::external
    click CI "https://github.com/ccleonos/leonos/blob/main/.github/workflows/release.yml"
    CI["CI/CD Workflow"]:::external
    click Lint "https://github.com/ccleonos/leonos/blob/main/.trae/rules/project_rules.md"
    Lint["Lint & Style Rules"]:::external
    Metadata["pack.mcmeta"]:::external
    click Metadata "https://github.com/ccleonos/leonos/blob/main/pack.mcmeta"
    GitHub -->|"triggers release"| CI
    GitHub -->|"source for installer/updater"| Installer
    GitHub -->|"source for updates"| Updater

    %% Local Filesystem
    subgraph LocalFS["Local File System"]
        Bootloader["Bootloader (unbios.lua)"]:::installer
        click Bootloader "https://github.com/ccleonos/leonos/blob/main/unbios.lua"
        BIOSEntrypoint["BIOS Entrypoint (bios.lua)"]:::runtime
        click BIOSEntrypoint "https://github.com/ccleonos/leonos/blob/main/data/computercraft/lua/bios.lua"
        subgraph "ROM Image"
            Startup["Startup Scripts\n(00_fs.lua → 90_settings.lua)"]:::runtime
            click Startup "https://github.com/ccleonos/leonos/blob/main/data/computercraft/lua/rom/startup/00_fs.lua"
            APIs["APIs Layer"]:::runtime
            click APIs "https://github.com/ccleonos/leonos/tree/main/data/computercraft/lua/rom/apis/"
            Modules["Modules & Libraries"]:::runtime
            click Modules "https://github.com/ccleonos/leonos/tree/main/data/computercraft/lua/rom/modules/"
            Programs["Shell Programs & Utilities"]:::runtime
            click Programs "https://github.com/ccleonos/leonos/tree/main/data/computercraft/lua/rom/programs/"
            Completions["Shell Completions"]:::runtime
            click Completions "https://github.com/ccleonos/leonos/tree/main/data/computercraft/lua/rom/completions/"
            Editors["In-Game Editors"]:::runtime
            click Editors "https://github.com/ccleonos/leonos/tree/main/data/computercraft/lua/rom/editors/"
            Help["Help Files"]:::runtime
            click Help "https://github.com/ccleonos/leonos/tree/main/data/computercraft/lua/rom/help/"
            Keymaps["Keymaps"]:::runtime
            click Keymaps "https://github.com/ccleonos/leonos/tree/main/data/computercraft/lua/rom/keymaps/"
            Packages["Package Support"]:::runtime
            click Packages "https://github.com/ccleonos/leonos/tree/main/data/computercraft/lua/packages/"
            InstalledIndex["Installed Index"]:::runtime
            click InstalledIndex "https://github.com/ccleonos/leonos/blob/main/data/computercraft/lua/packages/installed.json"
        end
        Updater["In-System Updater (updater.lua)"]:::installer
        click Updater "https://github.com/ccleonos/leonos/blob/main/updater.lua"
        Orchestrator["Update Orchestrator (update.lua)"]:::installer
        click Orchestrator "https://github.com/ccleonos/leonos/blob/main/data/computercraft/lua/rom/update.lua"
    end

    %% Boot Sequence
    Installer --> Bootloader
    Bootloader -->|"load BIOS entrypoint"| BIOSEntrypoint
    BIOSEntrypoint -->|"invoke startup scripts"| Startup
    Startup --> APIs
    APIs --> Modules
    Modules --> Programs
    Programs --> User

    %% Update Flow
    User -->|"run updater.lua"| Updater
    Updater -->|"invoke update.lua"| Orchestrator
    Orchestrator -->|"fetch update manifests"| GitHub
    Orchestrator -->|"write new ROM files"| LocalFS

    %% Styles
    classDef installer fill:#D0E8FF,stroke:#4A90E2,color:#000
    classDef runtime fill:#E0FFE0,stroke:#3C763D,color:#000
    classDef external fill:#FFE0B2,stroke:#E67E22,color:#000
```
