src/backend/doc/Kernel.md

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 servicesc 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.