# cia-foundation/templeos architecture

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

- Interactive diagram: https://gitdiagram.com/cia-foundation/templeos
- Repository: https://github.com/cia-foundation/templeos

## Overview

#### Purpose and Execution Model
TempleOS is a self-hosted, 64-bit operating system written in HolyC and assembly. It boots from an ISO/CD/DVD or VM-mounted image; source is compressed and compiled only inside the running OS by its native compiler. There is no conventional host-side build pipeline. The root startup path is `StartOS.HC`, with bootstrap code in `0000Boot/0000Kernel.BIN.C` and kernel initialization centered on `Kernel/KMain.HC`.

#### Boot, Kernel, and Hardware Boundary
The boot sequence transitions through 16-, 32-, and 64-bit startup stages, then initializes kernel globals, memory, tasks, interrupts, display, and devices. Core paths: `Kernel/KStart16.HC`, `Kernel/KStart64.HC`, `Kernel/KLoad.HC`. Hardware-facing services include ATA/CD/DVD block devices, keyboard/mouse serial devices, PCI BIOS access, display, and multiprocessor support. TempleOS may require manually supplied ATA/SATA I/O ports; no external network or cloud services are indicated.

#### Runtime: Tasks, Memory, and Core Services
The kernel provides the execution substrate for all interactive and compiled HolyC code: scheduler/task model, job execution, exception/debug support, heaps/paging, strings, hashes, and system configuration. Architectural anchors are `Kernel/Sched.HC`, `Kernel/KTask.HC`, `Kernel/Mem/MemPag.HC`, and `Kernel/Mem/PageTables.HC`. Higher layers call these kernel-resident facilities directly rather than crossing process or service boundaries typical of hosted OSes.

#### Storage and Filesystems
Block-device drivers feed a unified disk/file layer supporting TempleOS’s RedSea filesystem plus FAT and ISO media. The flow is physical ATA/CD/DVD access → block/cache/cluster logic → filesystem-specific directory/file operations → application-facing file APIs. Key boundaries: `Kernel/BlkDev/DskATA.HC`, `Kernel/BlkDev/DskCache.HC`, `Kernel/BlkDev/FileSysRedSea.HC`, `Kernel/BlkDev/FileSysFAT.HC`, and `Kernel/BlkDev/FileSysISO.HC`. User-facing mount, format, check, and file-manager operations sit in `Adam/ABlkDev/Mount.HC` and related modules.

#### HolyC Compiler and Self-Hosting
The native compiler lexes/parses HolyC, resolves symbols/assembly, applies optimization passes, and emits/loads executable code into the live OS environment. Its principal pipeline is represented by `Compiler/Lex.HC`, `Compiler/PrsExp.HC`, `Compiler/BackA.HC`, `Compiler/AsmResolve.HC`, and `Compiler/CMain.HC`. `Compiler/Compiler.BIN` is the supplied compiler binary; source and runtime are tightly coupled to the TempleOS environment.

#### Interactive Desktop and Document System
“Adam” is the high-level OS environment: windows, menus, controls, graphics, sound, autocomplete, and the DolDoc editor/document runtime. DolDoc documents (`.DD`) combine editable rich text with executable/code-oriented interactions. Main components include `Adam/WinMgr.HC`, `Adam/Menu.HC`, `Adam/DolDoc/DocEd.HC`, `Adam/DolDoc/DocRun.HC`, and `Adam/Gr/GrInitA.HC`. Input/control flow runs from kernel device input through window/control dispatch into documents and applications.

#### Applications, Content, and Distribution
Applications are in-tree HolyC programs launched through per-app `Load.HC`/`Run.HC` entry points, e.g. `Apps/Psalmody/Run.HC`, `Apps/ToTheFront/Run.HC`, and `Apps/Budget/Run.HC`. `Demo/` provides executable examples and games, while `Doc/` is the native documentation corpus. Install, boot-media, and distribution workflows are implemented in `Misc/OSInstall.HC`, `Misc/DoDistro.HC`, and `Adam/Opt/Boot/MakeBoot.HC`. Linux utilities such as `Linux/TOSZ.CPP` support archive/compression handling externally but do not provide a host compiler.

Main entry points: [`Kernel/KMain.HC`](https://github.com/cia-foundation/templeos/blob/archive/Kernel/KMain.HC) (Kernel initialization), [`Kernel/BlkDev/FileSysRedSea.HC`](https://github.com/cia-foundation/templeos/blob/archive/Kernel/BlkDev/FileSysRedSea.HC) (RedSea, FAT, ISO filesystems), [`Kernel/KLoad.HC`](https://github.com/cia-foundation/templeos/blob/archive/Kernel/KLoad.HC) (Hardware devices), [`Compiler/AsmResolve.HC`](https://github.com/cia-foundation/templeos/blob/archive/Compiler/AsmResolve.HC) (Assembly resolution and codegen)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_boot["Boot and Kernel"]
  node_boot_media["ISO / VM boot media<br/>boot image"]
  node_start_os["StartOS<br/>startup entry<br/>[StartOS.HC]"]
  node_bootstrap["Bootstrap kernel image<br/>[0000Kernel.BIN.C]"]
  node_kernel_start["16/64-bit startup<br/>CPU transition<br/>[KStart64.HC]"]
  node_kernel_init{{"Kernel initialization<br/>kernel core<br/>[KMain.HC]"}}
  node_task_runtime["Tasks and scheduler<br/>kernel runtime<br/>[Sched.HC]"]
  node_memory["Paging and heaps<br/>memory subsystem<br/>[MemPag.HC]"]
  node_devices["Hardware devices<br/>device services<br/>[KLoad.HC]"]
end

subgraph group_storage["Storage"]
  node_block_cache["Block and cache layer<br/>storage core<br/>[DskCache.HC]"]
  node_filesystems["RedSea, FAT, ISO filesystems<br/>filesystem layer<br/>[FileSysRedSea.HC]"]
  node_disk_tools["Mount and disk tools<br/>storage UI<br/>[Mount.HC]"]
end

subgraph group_compiler["HolyC Runtime"]
  node_compiler_binary["Supplied compiler binary<br/>compiler image<br/>[Compiler.BIN]"]
  node_compiler_frontend["HolyC lexer and parser<br/>compiler frontend<br/>[PrsExp.HC]"]
  node_compiler_backend["Assembly resolution and codegen<br/>compiler backend<br/>[AsmResolve.HC]"]
end

subgraph group_desktop["Adam Desktop"]
  node_desktop["Windows and controls<br/>desktop runtime<br/>[WinMgr.HC]"]
  node_doldoc["DolDoc editor and runner<br/>document runtime<br/>[DocRun.HC]"]
end

subgraph group_content["Apps and Distribution"]
  node_applications["In-tree applications<br/>HolyC applications<br/>[Run.HC]"]
  node_docs_demos["Docs and demos<br/>content corpus"]
  node_distribution["Install and boot-media workflow<br/>distribution tooling<br/>[DoDistro.HC]"]
  node_linux_tools["Linux archive utility<br/>external utility<br/>[TOSZ.CPP]"]
end

node_boot_media -->|"boots"| node_start_os
node_start_os -->|"loads"| node_bootstrap
node_bootstrap -->|"enters"| node_kernel_start
node_kernel_start -->|"initializes"| node_kernel_init
node_kernel_init -->|"starts"| node_task_runtime
node_kernel_init -->|"configures"| node_memory
node_kernel_init -->|"brings up"| node_devices
node_devices -->|"block I/O"| node_block_cache
node_block_cache -->|"serves blocks"| node_filesystems
node_filesystems -->|"mounts and manages"| node_disk_tools
node_filesystems -->|"loads"| node_compiler_binary
node_compiler_binary -->|"runs"| node_compiler_frontend
node_compiler_frontend -->|"parses HolyC"| node_compiler_backend
node_compiler_backend -->|"loads live code into"| node_task_runtime
node_devices -->|"input and display"| node_desktop
node_desktop -->|"hosts"| node_doldoc
node_doldoc -->|"executes HolyC through"| node_compiler_frontend
node_compiler_backend -->|"compiles and loads"| node_applications
node_desktop -->|"launches"| node_applications
node_filesystems -->|"stores"| node_docs_demos
node_distribution -->|"creates"| node_boot_media
node_linux_tools -.->|"archives externally"| node_distribution

click node_start_os "https://github.com/cia-foundation/templeos/blob/archive/StartOS.HC"
click node_bootstrap "https://github.com/cia-foundation/templeos/blob/archive/0000Boot/0000Kernel.BIN.C"
click node_kernel_start "https://github.com/cia-foundation/templeos/blob/archive/Kernel/KStart64.HC"
click node_kernel_init "https://github.com/cia-foundation/templeos/blob/archive/Kernel/KMain.HC"
click node_task_runtime "https://github.com/cia-foundation/templeos/blob/archive/Kernel/Sched.HC"
click node_memory "https://github.com/cia-foundation/templeos/blob/archive/Kernel/Mem/MemPag.HC"
click node_devices "https://github.com/cia-foundation/templeos/blob/archive/Kernel/KLoad.HC"
click node_block_cache "https://github.com/cia-foundation/templeos/blob/archive/Kernel/BlkDev/DskCache.HC"
click node_filesystems "https://github.com/cia-foundation/templeos/blob/archive/Kernel/BlkDev/FileSysRedSea.HC"
click node_disk_tools "https://github.com/cia-foundation/templeos/blob/archive/Adam/ABlkDev/Mount.HC"
click node_compiler_binary "https://github.com/cia-foundation/templeos/blob/archive/Compiler/Compiler.BIN"
click node_compiler_frontend "https://github.com/cia-foundation/templeos/blob/archive/Compiler/PrsExp.HC"
click node_compiler_backend "https://github.com/cia-foundation/templeos/blob/archive/Compiler/AsmResolve.HC"
click node_desktop "https://github.com/cia-foundation/templeos/blob/archive/Adam/WinMgr.HC"
click node_doldoc "https://github.com/cia-foundation/templeos/blob/archive/Adam/DolDoc/DocRun.HC"
click node_applications "https://github.com/cia-foundation/templeos/blob/archive/Apps/Psalmody/Run.HC"
click node_distribution "https://github.com/cia-foundation/templeos/blob/archive/Misc/DoDistro.HC"
click node_linux_tools "https://github.com/cia-foundation/templeos/blob/archive/Linux/TOSZ.CPP"

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_media,node_start_os,node_bootstrap,node_kernel_start,node_kernel_init,node_task_runtime,node_memory,node_devices toneBlue
class node_block_cache,node_filesystems,node_disk_tools toneAmber
class node_compiler_binary,node_compiler_frontend,node_compiler_backend toneMint
class node_desktop,node_doldoc toneRose
class node_applications,node_docs_demos,node_distribution,node_linux_tools toneIndigo
```

## Components

### Boot and Kernel

- **ISO / VM boot media**: boot image · Bootable media contains the compressed self-hosted system.
- [StartOS](https://github.com/cia-foundation/templeos/blob/archive/StartOS.HC): startup entry · `StartOS.HC`
- [Bootstrap kernel image](https://github.com/cia-foundation/templeos/blob/archive/0000Boot/0000Kernel.BIN.C): bootstrap · `0000Boot/0000Kernel.BIN.C`
- [16/64-bit startup](https://github.com/cia-foundation/templeos/blob/archive/Kernel/KStart64.HC): CPU transition · `Kernel/KStart64.HC`
- [Kernel initialization](https://github.com/cia-foundation/templeos/blob/archive/Kernel/KMain.HC): kernel core · Initializes globals, tasks, interrupts, display, and devices. · `Kernel/KMain.HC`
- [Tasks and scheduler](https://github.com/cia-foundation/templeos/blob/archive/Kernel/Sched.HC): kernel runtime · `Kernel/Sched.HC`
- [Paging and heaps](https://github.com/cia-foundation/templeos/blob/archive/Kernel/Mem/MemPag.HC): memory subsystem · `Kernel/Mem/MemPag.HC`
- [Hardware devices](https://github.com/cia-foundation/templeos/blob/archive/Kernel/KLoad.HC): device services · ATA/CD/DVD, input, display, PCI BIOS, and multiprocessor support. · `Kernel/KLoad.HC`

### Storage

- [Block and cache layer](https://github.com/cia-foundation/templeos/blob/archive/Kernel/BlkDev/DskCache.HC): storage core · `Kernel/BlkDev/DskCache.HC`
- [RedSea, FAT, ISO filesystems](https://github.com/cia-foundation/templeos/blob/archive/Kernel/BlkDev/FileSysRedSea.HC): filesystem layer · `Kernel/BlkDev/FileSysRedSea.HC`
- [Mount and disk tools](https://github.com/cia-foundation/templeos/blob/archive/Adam/ABlkDev/Mount.HC): storage UI · `Adam/ABlkDev/Mount.HC`

### HolyC Runtime

- [Supplied compiler binary](https://github.com/cia-foundation/templeos/blob/archive/Compiler/Compiler.BIN): compiler image · Loaded inside TempleOS; it is not a host build tool. · `Compiler/Compiler.BIN`
- [HolyC lexer and parser](https://github.com/cia-foundation/templeos/blob/archive/Compiler/PrsExp.HC): compiler frontend · `Compiler/PrsExp.HC`
- [Assembly resolution and codegen](https://github.com/cia-foundation/templeos/blob/archive/Compiler/AsmResolve.HC): compiler backend · Emits and loads executable code into the live OS. · `Compiler/AsmResolve.HC`

### Adam Desktop

- [Windows and controls](https://github.com/cia-foundation/templeos/blob/archive/Adam/WinMgr.HC): desktop runtime · `Adam/WinMgr.HC`
- [DolDoc editor and runner](https://github.com/cia-foundation/templeos/blob/archive/Adam/DolDoc/DocRun.HC): document runtime · Editable documents combine rich text and executable interactions. · `Adam/DolDoc/DocRun.HC`

### Apps and Distribution

- [In-tree applications](https://github.com/cia-foundation/templeos/blob/archive/Apps/Psalmody/Run.HC): HolyC applications · Programs use per-application Load.HC and Run.HC entry points. · `Apps/Psalmody/Run.HC`
- **Docs and demos**: content corpus · Native documentation plus executable examples and games.
- [Install and boot-media workflow](https://github.com/cia-foundation/templeos/blob/archive/Misc/DoDistro.HC): distribution tooling · `Misc/DoDistro.HC`
- [Linux archive utility](https://github.com/cia-foundation/templeos/blob/archive/Linux/TOSZ.CPP): external utility · Supports archive/compression handling only; it does not compile TempleOS. · `Linux/TOSZ.CPP`

## Connections

- ISO / VM boot media → StartOS: boots
- StartOS → Bootstrap kernel image: loads
- Bootstrap kernel image → 16/64-bit startup: enters
- 16/64-bit startup → Kernel initialization: initializes
- Kernel initialization → Tasks and scheduler: starts
- Kernel initialization → Paging and heaps: configures
- Kernel initialization → Hardware devices: brings up
- Hardware devices → Block and cache layer: block I/O
- Block and cache layer → RedSea, FAT, ISO filesystems: serves blocks
- RedSea, FAT, ISO filesystems → Mount and disk tools: mounts and manages
- RedSea, FAT, ISO filesystems → Supplied compiler binary: loads
- Supplied compiler binary → HolyC lexer and parser: runs
- HolyC lexer and parser → Assembly resolution and codegen: parses HolyC
- Assembly resolution and codegen → Tasks and scheduler: loads live code into
- Hardware devices → Windows and controls: input and display
- Windows and controls → DolDoc editor and runner: hosts
- DolDoc editor and runner → HolyC lexer and parser: executes HolyC through
- Assembly resolution and codegen → In-tree applications: compiles and loads
- Windows and controls → In-tree applications: launches
- RedSea, FAT, ISO filesystems → Docs and demos: stores
- Install and boot-media workflow → ISO / VM boot media: creates
- Linux archive utility → Install and boot-media workflow: archives externally
