From 1e0fb1c3c5b855210b4a5914f3d051fb78a1b98a Mon Sep 17 00:00:00 2001
From: KernelDeimos <eric.alex.dube@gmail.com>
Date: Fri, 6 Dec 2024 13:05:01 -0500
Subject: [PATCH] doc: document kernel behavior

---
 src/backend/doc/Kernel.md | 65 +++++++++++++++++++++++++++++++++++++++
 1 file changed, 65 insertions(+)
 create mode 100644 src/backend/doc/Kernel.md

diff --git a/src/backend/doc/Kernel.md b/src/backend/doc/Kernel.md
new file mode 100644
index 00000000..0cb15ef0
--- /dev/null
+++ b/src/backend/doc/Kernel.md
@@ -0,0 +1,65 @@
+# Puter Kernel Documentation
+
+## Overview
+
+The **Puter Kernel** is the core runtime component of the Puter system. It provides the foundational infrastructure for:
+
+- Initializing the runtime environment
+- Managing internal and external modules (extensions)
+- Setting up and booting core services
+- Configuring logging and debugging utilities
+- Integrating with third-party modules and performing dependency installs at runtime
+
+This kernel is responsible for orchestrating the startup sequence and ensuring that all necessary services, modules, and environmental configurations are properly loaded before the application enters its operational state.
+
+---
+
+## Features
+
+1. **Modular Architecture**:  
+   The Kernel supports both internal and external modules:
+   - **Internal Modules**: Provided to Kernel by an initializing script, such
+     as `tools/run-selfhosted.js`, via the `add_module()` method.
+   - **External Modules**: Discovered in configured module directories and installed
+     dynamically. This includes resolving and executing `package.json` entries and
+     running `npm install` as needed.
+
+2. **Service Container & Registry**:  
+   The Kernel initializes a service container that manages a wide range of services. Services can:
+   - Register modules
+   - Initialize dependencies
+   - Emit lifecycle events (`boot.consolidation`, `boot.activation`, `boot.ready`) to
+     orchestrate a stable and consistent environment.
+
+3. **Runtime Environment Setup**:  
+   The Kernel sets up a `RuntimeEnvironment` to determine configuration paths and environment parameters. It also provides global helpers like `kv` for key-value storage and `cl` for simplified console logging.
+
+4. **Logging and Debugging**:  
+   Uses a temporary `BootLogger` for the initialization phase until LogService is
+   initialized, at which point it will replace the boot logger. Debugging features
+   (`ll`, `xtra_log`) are enabled in development environments for convenience.
+
+## Initialization & Boot Process
+
+1. **Constructor**:  
+   When a Kernel instance is created, it sets up basic parameters, initializes an empty
+   module list, and prepares `useapi()` integration.
+
+2. **Booting**:  
+   The `boot()` method:
+   - Parses CLI arguments using `yargs`.
+   - Calls `_runtime_init()` to set up the `RuntimeEnvironment` and boot logger.
+   - Initializes global debugging/logging utilities.
+   - Sets up the service container (usually called `services`c instance of **Container**).
+   - Invokes module installation and service bootstrapping processes.
+
+3. **Module Installation**:  
+   Internal modules are registered and installed first.  
+   External modules are discovered, packaged, installed, and their code is executed.  
+   External modules are given a special context with access to `useapi()`, a dynamic
+   import mechanism for Puter modules and extensions.
+
+4. **Service Bootstrapping**:  
+   After modules and extensions are installed, services are initialized and activated.
+   For more information about how this works, see [boot-sequence.md](./contributors/boot-sequence.md).
+