# ticonderoga2017/starry-next architecture

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

- Interactive diagram: https://gitdiagram.com/ticonderoga2017/starry-next
- Repository: https://github.com/ticonderoga2017/starry-next

## Overview

##### Project type and purpose
- StarryOS is a monolithic operating‐system kernel (written in Rust), derived from ArceOS, plus a suite of user‐space test applications and build/runtime tooling. It’s not a web app or microservice, but a low‐level OS kernel with a userland test harness.

##### File structure
- Top‐level crates and folders:
- src/           → the kernel’s entry point, main loop, syscall dispatcher, mm, task management
- core/          → core kernel library (futex, memory management, task structs, timers)
- api/           → user‐kernel interface crate (file, pipe, stdio, signal, networking abstractions)
- build.rs, Makefile, scripts/ → build pipeline, config generation, image creation
- configs/       → target‐specific TOML files (x86_64, riscv64, aarch64, loongarch64)
- apps/          → user applications grouped by test suite (libc, nimbos, junior, oscomp)
- .devcontainer, Dockerfile → developer container for consistent Rust/musl build environment
- .github/workflows → CI automation
- The project uses Cargo (Rust), Makefiles, shell scripts, Docker, QEMU.

##### README for additional insights
- Describes build & run recipes:
- Dependency fetch via scripts/get_deps.sh
- Building user apps, kernel, and creating disk image
- Running in QEMU with various architectures and features

##### Main components and their interactions
a. Developer & Build Environment
- Host machine → Docker container (or native)
- scripts/get_deps.sh → installs musl toolchains, qemu, cargo‐binutils
- Cargo + Makefiles + build.rs → compile core/, api/, and src/ crates into a kernel binary
- scripts/build_img.sh → packages user apps into a filesystem image
b. Kernel components (monolithic)
- Entry & init (src/entry.rs, main.rs)
- System call layer (src/syscall.rs)
- Memory management (src/mm.rs; core/src/mm.rs; api/src/imp/mm)
- Task & scheduler (core/src/task.rs; api/src/imp/task)
- File system & I/O (api/src/file, api/src/imp/fs)
- Signals, futex (api/src/imp/signal.rs; api/src/imp/futex.rs)
- Time & timers (api/src/time.rs; core/src/time.rs)
c. User‐space applications
- Built under apps/… → static binaries for each architecture
- Link against api crate interfaces (syscalls)
d. QEMU VM
- Loads kernel binary + disk image (with apps)
- Simulates hardware: CPU, memory, block (BLK), network (NET), acceleration (ACCEL)

##### Architectural patterns & design principles
- Modular monolith: each subsystem lives in its own Rust module/crate but linked into one kernel binary
- Clear crate‐level API boundary: core (kernel internals), api (public syscall interface), src (glue code)
- Host ↔ Target separation: host tools build, then produce artifacts for target QEMU runtime
- Cross‐compilation via musl toolchains ensures portability across four CPU architectures.

- Clear labels on every component (e.g., “api crate”, “core crate”, “scheduler module”)
- Build pipeline (source → compiler → binary)
- Runtime syscalls and I/O paths

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Build Environment"
        host["Developer Host"]:::external
        docker(("Docker Container")):::external
        deps["scripts/get_deps.sh"]:::build
        make["Makefile"]:::build
        buildrs["build.rs"]:::build
        configs["configs/"]:::build
        cargo(("Cargo")):::build
        build_img["build_img.sh"]:::build
    end

    host --> docker
    docker --> deps
    docker --> make
    deps --> cargo
    make --> cargo
    buildrs --> cargo
    configs --> cargo
    cargo -->|"build kernel"| kernel_binary
    cargo -->|"compile user apps"| apps_disk

    click deps "https://github.com/ticonderoga2017/starry-next/blob/main/scripts/get_deps.sh"
    click build_img "https://github.com/ticonderoga2017/starry-next/blob/main/build_img.sh"
    click docker "https://github.com/ticonderoga2017/starry-next/tree/main/.devcontainer/Dockerfile"
    click make "https://github.com/ticonderoga2017/starry-next/tree/main/Makefile"
    click buildrs "https://github.com/ticonderoga2017/starry-next/blob/main/build.rs"
    click configs "https://github.com/ticonderoga2017/starry-next/tree/main/configs/"

    subgraph "Kernel Binary & Disk Image"
        kernel_binary(("Kernel Binary")):::crate
        disk_img(("Disk Image")):::external
        subgraph "Crates"
            core_crate["core crate"]:::crate
            api_crate["api crate"]:::crate
            src_crate["src crate"]:::crate
        end
        core_crate --> api_crate
        api_crate --> src_crate
        src_crate --> kernel_binary
        apps_disk --> disk_img
    end

    click core_crate "https://github.com/ticonderoga2017/starry-next/blob/main/core/Cargo.toml"
    click api_crate "https://github.com/ticonderoga2017/starry-next/blob/main/api/Cargo.toml"
    click src_crate "https://github.com/ticonderoga2017/starry-next/blob/main/Cargo.toml"

    subgraph "Runtime: QEMU VM"
        qemu(("QEMU VM")):::external
        kernel_bin_runtime(("Monolithic Kernel")):::crate
        disk_runtime(("ext4 Disk")):::external

        subgraph "Kernel Modules"
            entry["entry & init"]:::subsys
            mainloop["main loop"]:::subsys
            syscall["syscall dispatcher"]:::subsys
            mm["memory management"]:::subsys
            task["task scheduler"]:::subsys
            fs["filesystem & I/O"]:::subsys
            signal["signals & futex"]:::subsys
            time["time & timers"]:::subsys
        end

        subgraph "Hardware Devices"
            cpu(("CPU")):::external
            mmu(("MMU")):::external
            blk(("Block Device")):::external
            net(("Network")):::external
        end

        qemu --> kernel_bin_runtime
        qemu --> disk_runtime
        kernel_bin_runtime --> entry
        kernel_bin_runtime --> mainloop
        kernel_bin_runtime --> syscall
        kernel_bin_runtime --> mm
        kernel_bin_runtime --> task
        kernel_bin_runtime --> fs
        kernel_bin_runtime --> signal
        kernel_bin_runtime --> time
        disk_runtime -->|"user apps"| syscall
        syscall --> mm
        syscall --> fs
        syscall --> signal
        syscall --> task
        kernel_bin_runtime --> cpu
        kernel_bin_runtime --> mmu
        fs --> blk
        fs --> net
    end

    click entry "https://github.com/ticonderoga2017/starry-next/blob/main/src/entry.rs"
    click mainloop "https://github.com/ticonderoga2017/starry-next/blob/main/src/main.rs"
    click syscall "https://github.com/ticonderoga2017/starry-next/blob/main/src/syscall.rs"
    click mm "https://github.com/ticonderoga2017/starry-next/blob/main/src/mm.rs"
    click coremm "https://github.com/ticonderoga2017/starry-next/blob/main/core/src/mm.rs"
    click apimm "https://github.com/ticonderoga2017/starry-next/tree/main/api/src/imp/mm/"
    click coretask "https://github.com/ticonderoga2017/starry-next/blob/main/core/src/task.rs"
    click apitask "https://github.com/ticonderoga2017/starry-next/tree/main/api/src/imp/task/"
    click apifs "https://github.com/ticonderoga2017/starry-next/tree/main/api/src/file/"
    click fsimp "https://github.com/ticonderoga2017/starry-next/tree/main/api/src/imp/fs/"
    click signal_api "https://github.com/ticonderoga2017/starry-next/blob/main/api/src/signal.rs"
    click futex_imp "https://github.com/ticonderoga2017/starry-next/blob/main/api/src/imp/futex.rs"
    click signal_imp "https://github.com/ticonderoga2017/starry-next/blob/main/api/src/imp/signal.rs"
    click coretime "https://github.com/ticonderoga2017/starry-next/blob/main/core/src/time.rs"
    click apitime "https://github.com/ticonderoga2017/starry-next/blob/main/api/src/time.rs"
    click timeimp "https://github.com/ticonderoga2017/starry-next/blob/main/api/src/imp/time.rs"
    click junior "https://github.com/ticonderoga2017/starry-next/tree/main/apps/junior/"
    click libcapp "https://github.com/ticonderoga2017/starry-next/tree/main/apps/libc/"
    click nimbos "https://github.com/ticonderoga2017/starry-next/tree/main/apps/nimbos/"
    click oscomp "https://github.com/ticonderoga2017/starry-next/tree/main/apps/oscomp/"
    click ci "https://github.com/ticonderoga2017/starry-next/blob/main/.github/workflows/ci.yml"

    classDef build fill:#AED6F1,stroke:#21618C,color:#1B4F72
    classDef external fill:#D6DBDF,stroke:#808B96,color:#2C3E50
    classDef crate fill:#A9DFBF,stroke:#196F3D,color:#145A32
    classDef subsys fill:#F9E79F,stroke:#B7950B,color:#7D6608
```
