# satanacio666/neo-os architecture

> Architecture diagram of the GitHub repository satanacio666/neo-os, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-18). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/satanacio666/neo-os
- Repository: https://github.com/satanacio666/neo-os

## Overview

NeoOS is a bare-metal AArch64, single-address-space operating system booted through UEFI. The main path is UEFI startup and display/memory setup, followed by kernel services and the interactive HolyC environment; users can run scripts, use the filesystem, and interact with the graphical desktop and 3D renderer. The graph also preserves documented SMP, scheduling, and hardware-driver capabilities. Some subsystems are represented from README claims and source-tree paths; their internal wiring is omitted where sampled evidence does not show it.

Main entry points: [`boot/main.c`](https://github.com/satanacio666/neo-os/blob/main/boot/main.c) (UEFI bootstrap), [`gui/render.c`](https://github.com/satanacio666/neo-os/blob/main/gui/render.c) (2D canvas and DolDoc), [`drivers/gpu/gfx_backend.c`](https://github.com/satanacio666/neo-os/blob/main/drivers/gpu/gfx_backend.c) (Graphics backend), [`kernel/mem/kheap.c`](https://github.com/satanacio666/neo-os/blob/main/kernel/mem/kheap.c) (Kernel heap)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_boot_runtime["Boot and kernel"]
  node_boot["UEFI bootstrap<br/>[main.c]"]
  node_platform["AArch64 platform<br/>[hal_platform.c]"]
  node_heap["Kernel heap<br/>[kheap.c]"]
  node_symbols["Symbol registry<br/>[symbols.c]"]
  node_smp["Core startup<br/>[smp.c]"]
  node_scheduler["Task scheduler<br/>[sched.c]"]
end

subgraph group_language_storage["Language and storage"]
  node_jit["HolyC JIT<br/>[jit_arm64.c]"]
  node_lexer["HolyC lexer<br/>[lexer.c]"]
  node_block["VirtIO block driver<br/>[virtio_blk.c]"]
  node_redsea[("RedSea filesystem<br/>[redsea.c]")]
end

subgraph group_desktop_input["Desktop and input"]
  node_shell["Interactive shell<br/>[shell.c]"]
  node_window_manager["Window manager<br/>[wm.c]"]
  node_input_driver["VirtIO input<br/>[virtio_input.c]"]
  node_mouse["Mouse handling<br/>[mouse.c]"]
end

subgraph group_graphics_compute["Graphics and compute"]
  node_renderer["2D canvas and DolDoc<br/>[render.c]"]
  node_backend["Graphics backend<br/>[gfx_backend.c]"]
  node_gpu_driver["VirtIO GPU driver<br/>[virtio_gpu.c]"]
  node_math3d["3D transform and render<br/>[math3d.c]"]
  node_tile_raster["Tile rasterizer<br/>[raster_tile.c]"]
  node_holygl["HolyGL engine<br/>[holygl.c]"]
end

node_firmware(("UEFI firmware"))
node_display[("GOP framebuffer")]
node_user(("Operator"))

node_firmware -->|"starts"| node_boot
node_boot -->|"initializes"| node_platform
node_boot -->|"initializes"| node_heap
node_boot -->|"uses"| node_symbols
node_boot -->|"loads runtime"| node_jit
node_boot -->|"uses"| node_block
node_boot -->|"uses"| node_redsea
node_boot -->|"sets GOP mode"| node_display
node_jit -->|"parses with"| node_lexer
node_jit -->|"allocates via"| node_heap
node_jit -->|"resolves names"| node_symbols
node_lexer -->|"allocates via"| node_heap
node_lexer -->|"resolves names"| node_symbols
node_redsea -->|"reads and writes"| node_block
node_redsea -->|"allocates via"| node_heap
node_redsea -->|"registers commands"| node_symbols
node_input_driver -->|"updates position"| node_mouse
node_input_driver -->|"uses queue definitions"| node_block
node_mouse -->|"uses canvas"| node_renderer
node_backend -->|"uses canvas"| node_renderer
node_backend -->|"creates config window"| node_window_manager
node_backend -->|"uses rasterizer"| node_tile_raster
node_gpu_driver -->|"uses backend"| node_backend
node_gpu_driver -->|"uses VirtIO definitions"| node_block
node_math3d -->|"draws to"| node_renderer
node_math3d -->|"dispatches transforms"| node_smp
node_tile_raster -->|"uses core interface"| node_smp
node_tile_raster -->|"uses backend interface"| node_backend
node_tile_raster -->|"uses canvas"| node_renderer
node_renderer -->|"presents through"| node_backend
node_renderer -->|"allocates via"| node_heap
node_smp -->|"reports through"| node_renderer
node_smp -->|"uses registry"| node_symbols
node_scheduler -->|"allocates via"| node_heap
node_scheduler -->|"reports through"| node_renderer
node_scheduler -->|"uses core interface"| node_smp
node_user -.->|"interacts with"| node_shell
node_shell -.->|"runs scripts"| node_jit
node_shell -.->|"uses filesystem"| node_redsea
node_user -.->|"operates desktop"| node_window_manager
node_window_manager -.->|"renders windows"| node_renderer
node_holygl -.->|"uses 3D pipeline"| node_math3d
node_backend -.->|"optional hardware scanout"| node_gpu_driver

click node_boot "https://github.com/satanacio666/neo-os/blob/main/boot/main.c"
click node_platform "https://github.com/satanacio666/neo-os/blob/main/kernel/arch/aarch64/hal_platform.c"
click node_heap "https://github.com/satanacio666/neo-os/blob/main/kernel/mem/kheap.c"
click node_symbols "https://github.com/satanacio666/neo-os/blob/main/kernel/symbols/symbols.c"
click node_smp "https://github.com/satanacio666/neo-os/blob/main/kernel/arch/aarch64/smp.c"
click node_scheduler "https://github.com/satanacio666/neo-os/blob/main/kernel/sched/sched.c"
click node_jit "https://github.com/satanacio666/neo-os/blob/main/compiler/jit_arm64.c"
click node_lexer "https://github.com/satanacio666/neo-os/blob/main/compiler/lexer.c"
click node_block "https://github.com/satanacio666/neo-os/blob/main/drivers/block/virtio_blk.c"
click node_redsea "https://github.com/satanacio666/neo-os/blob/main/fs/redsea.c"
click node_shell "https://github.com/satanacio666/neo-os/blob/main/gui/shell.c"
click node_window_manager "https://github.com/satanacio666/neo-os/blob/main/gui/wm.c"
click node_input_driver "https://github.com/satanacio666/neo-os/blob/main/drivers/input/virtio_input.c"
click node_mouse "https://github.com/satanacio666/neo-os/blob/main/drivers/input/mouse.c"
click node_renderer "https://github.com/satanacio666/neo-os/blob/main/gui/render.c"
click node_backend "https://github.com/satanacio666/neo-os/blob/main/drivers/gpu/gfx_backend.c"
click node_gpu_driver "https://github.com/satanacio666/neo-os/blob/main/drivers/gpu/virtio_gpu.c"
click node_math3d "https://github.com/satanacio666/neo-os/blob/main/kernel/math/math3d.c"
click node_tile_raster "https://github.com/satanacio666/neo-os/blob/main/kernel/math/raster_tile.c"
click node_holygl "https://github.com/satanacio666/neo-os/blob/main/kernel/math/holygl.c"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_boot,node_platform,node_heap,node_symbols,node_smp,node_scheduler toneBlue
class node_jit,node_lexer,node_block,node_redsea,node_display toneAmber
class node_shell,node_window_manager,node_input_driver,node_mouse toneMint
class node_renderer,node_backend,node_gpu_driver,node_math3d,node_tile_raster,node_holygl toneRose
class node_firmware,node_user toneIndigo
```

## Components

### Boot and kernel

- [UEFI bootstrap](https://github.com/satanacio666/neo-os/blob/main/boot/main.c): `boot/main.c`
- [AArch64 platform](https://github.com/satanacio666/neo-os/blob/main/kernel/arch/aarch64/hal_platform.c): `kernel/arch/aarch64/hal_platform.c`
- [Kernel heap](https://github.com/satanacio666/neo-os/blob/main/kernel/mem/kheap.c): `kernel/mem/kheap.c`
- [Symbol registry](https://github.com/satanacio666/neo-os/blob/main/kernel/symbols/symbols.c): `kernel/symbols/symbols.c`
- [Core startup](https://github.com/satanacio666/neo-os/blob/main/kernel/arch/aarch64/smp.c): `kernel/arch/aarch64/smp.c`
- [Task scheduler](https://github.com/satanacio666/neo-os/blob/main/kernel/sched/sched.c): `kernel/sched/sched.c`

### Language and storage

- [HolyC JIT](https://github.com/satanacio666/neo-os/blob/main/compiler/jit_arm64.c): `compiler/jit_arm64.c`
- [HolyC lexer](https://github.com/satanacio666/neo-os/blob/main/compiler/lexer.c): `compiler/lexer.c`
- [VirtIO block driver](https://github.com/satanacio666/neo-os/blob/main/drivers/block/virtio_blk.c): `drivers/block/virtio_blk.c`
- [RedSea filesystem](https://github.com/satanacio666/neo-os/blob/main/fs/redsea.c): `fs/redsea.c`

### Desktop and input

- [Interactive shell](https://github.com/satanacio666/neo-os/blob/main/gui/shell.c): `gui/shell.c`
- [Window manager](https://github.com/satanacio666/neo-os/blob/main/gui/wm.c): `gui/wm.c`
- [VirtIO input](https://github.com/satanacio666/neo-os/blob/main/drivers/input/virtio_input.c): `drivers/input/virtio_input.c`
- [Mouse handling](https://github.com/satanacio666/neo-os/blob/main/drivers/input/mouse.c): `drivers/input/mouse.c`

### Graphics and compute

- [2D canvas and DolDoc](https://github.com/satanacio666/neo-os/blob/main/gui/render.c): `gui/render.c`
- [Graphics backend](https://github.com/satanacio666/neo-os/blob/main/drivers/gpu/gfx_backend.c): `drivers/gpu/gfx_backend.c`
- [VirtIO GPU driver](https://github.com/satanacio666/neo-os/blob/main/drivers/gpu/virtio_gpu.c): `drivers/gpu/virtio_gpu.c`
- [3D transform and render](https://github.com/satanacio666/neo-os/blob/main/kernel/math/math3d.c): `kernel/math/math3d.c`
- [Tile rasterizer](https://github.com/satanacio666/neo-os/blob/main/kernel/math/raster_tile.c): `kernel/math/raster_tile.c`
- [HolyGL engine](https://github.com/satanacio666/neo-os/blob/main/kernel/math/holygl.c): `kernel/math/holygl.c`

### Other components

- **UEFI firmware**
- **GOP framebuffer**
- **Operator**

## Connections

- UEFI firmware → UEFI bootstrap: starts
- UEFI bootstrap → AArch64 platform: initializes (evidence: `boot/main.c`)
- UEFI bootstrap → Kernel heap: initializes (evidence: `boot/main.c`)
- UEFI bootstrap → Symbol registry: uses (evidence: `boot/main.c`)
- UEFI bootstrap → HolyC JIT: loads runtime (evidence: `boot/main.c`)
- UEFI bootstrap → VirtIO block driver: uses (evidence: `boot/main.c`)
- UEFI bootstrap → RedSea filesystem: uses (evidence: `boot/main.c`)
- UEFI bootstrap → GOP framebuffer: sets GOP mode (evidence: `boot/main.c`)
- HolyC JIT → HolyC lexer: parses with (evidence: `compiler/jit_arm64.c`)
- HolyC JIT → Kernel heap: allocates via (evidence: `compiler/jit_arm64.c`)
- HolyC JIT → Symbol registry: resolves names (evidence: `compiler/jit_arm64.c`)
- HolyC lexer → Kernel heap: allocates via (evidence: `compiler/lexer.c`)
- HolyC lexer → Symbol registry: resolves names (evidence: `compiler/lexer.c`)
- RedSea filesystem → VirtIO block driver: reads and writes (evidence: `fs/redsea.c`)
- RedSea filesystem → Kernel heap: allocates via (evidence: `fs/redsea.c`)
- RedSea filesystem → Symbol registry: registers commands (evidence: `fs/redsea.c`)
- VirtIO input → Mouse handling: updates position (evidence: `drivers/input/virtio_input.c`)
- VirtIO input → VirtIO block driver: uses queue definitions (evidence: `drivers/input/virtio_input.c`)
- Mouse handling → 2D canvas and DolDoc: uses canvas (evidence: `drivers/input/mouse.c`)
- Graphics backend → 2D canvas and DolDoc: uses canvas (evidence: `drivers/gpu/gfx_backend.c`)
- Graphics backend → Window manager: creates config window (evidence: `drivers/gpu/gfx_backend.c`)
- Graphics backend → Tile rasterizer: uses rasterizer (evidence: `drivers/gpu/gfx_backend.c`)
- VirtIO GPU driver → Graphics backend: uses backend (evidence: `drivers/gpu/virtio_gpu.c`)
- VirtIO GPU driver → VirtIO block driver: uses VirtIO definitions (evidence: `drivers/gpu/virtio_gpu.c`)
- 3D transform and render → 2D canvas and DolDoc: draws to (evidence: `kernel/math/math3d.c`)
- 3D transform and render → Core startup: dispatches transforms (evidence: `kernel/math/math3d.c`)
- Tile rasterizer → Core startup: uses core interface (evidence: `kernel/math/raster_tile.c`)
- Tile rasterizer → Graphics backend: uses backend interface (evidence: `kernel/math/raster_tile.c`)
- Tile rasterizer → 2D canvas and DolDoc: uses canvas (evidence: `kernel/math/raster_tile.c`)
- 2D canvas and DolDoc → Graphics backend: presents through (evidence: `gui/render.c`)
- 2D canvas and DolDoc → Kernel heap: allocates via (evidence: `gui/render.c`)
- Core startup → 2D canvas and DolDoc: reports through (evidence: `kernel/arch/aarch64/smp.c`)
- Core startup → Symbol registry: uses registry (evidence: `kernel/arch/aarch64/smp.c`)
- Task scheduler → Kernel heap: allocates via (evidence: `kernel/sched/sched.c`)
- Task scheduler → 2D canvas and DolDoc: reports through (evidence: `kernel/sched/sched.c`)
- Task scheduler → Core startup: uses core interface (evidence: `kernel/sched/sched.c`)
- Operator → Interactive shell: interacts with
- Interactive shell → HolyC JIT: runs scripts
- Interactive shell → RedSea filesystem: uses filesystem
- Operator → Window manager: operates desktop
- Window manager → 2D canvas and DolDoc: renders windows
- HolyGL engine → 3D transform and render: uses 3D pipeline
- Graphics backend → VirtIO GPU driver: optional hardware scanout