# Core Architecture

## Runtime Path

```text
User -> khy CLI (Python) -> Node CLI router -> services/routes -> data/storage
```

## Alpine-Inspired Boot Layering (Reference Model)

This project can follow Alpine's layered boot idea:

```text
Bootloader -> minimal init/bootstrap -> core runtime -> upper apps/plugins
```

Mapping to Khy OS:

- Boot/entry:
  - `khy_quant/cli.py` (Python launcher, environment checks, bootstrap handoff)
- Core runtime:
  - `backend/bin/khyquant.js` + `backend/src/bootstrap/*` + CLI router/services
- Upper-layer app/plugin:
  - `khyquant` as default app compatibility entry
  - `backend/src/cli/handlers/app.js` + plugin/skill ecosystem

Practical rule:

- Keep `khy` as OS-level primary command.
- Keep app logic (such as quant trading) as replaceable upper-layer modules.

## Concrete Reference Points from `alpine-standard-3.23.0-x86_64.iso`

- Minimal boot config:
  - `/BOOT/GRUB/GRUB.CFG;1`
  - `/BOOT/SYSLINUX/SYSLINUX.CFG;1`
  - Keep boot path small and deterministic.
- Layered runtime artifacts:
  - kernel: `/BOOT/VMLINUZ_LTS.;1`
  - early userspace: `/BOOT/INITRAMFS_LTS.;1`
  - modular runtime image: `/BOOT/MODLOOP_LTS.;1`
- Package-driven system assembly:
  - `/APKS/X86_64/APKINDEX_TAR.GZ;1` + APK packages.
  - Equivalent in Khy OS: keep app/plugin install/update as package/index driven.
- Explicit init-to-runtime handoff:
  - initramfs `init` script finishes with `switch_root`.
  - Equivalent in Khy OS: keep launcher/bootstrap/runtime boundaries explicit and testable.
- Signed module trust chain:
  - modloop signature keys are staged before package install.
  - Equivalent in Khy OS: plugin/runtime artifacts should be verifiable before activation.

## Layer Mapping (Current Khy OS)

### 1) App Layer

- Browser apps (Vue UI), CLI apps, and external plugin apps.
- WASM apps are registered and executed through:
  - `backend/src/cli/handlers/app.js`
  - `backend/src/services/wasmAppService.js`

### 2) WASM Sandbox Layer

- Pure logic modules run in WebAssembly (MoonBit/Rust/C/C++ compiled to WASM).
- Host keeps I/O, network, file, process, and device access.
- Browser-side bridge:
  - `frontend/src/services/wasm/wasmBridge.js`

### 3) OS Component Layer

- Backend services are split by responsibility (gateway, routing, data, auth, plugins).
- Components communicate through explicit APIs/commands instead of direct UI coupling.

### 4) IPC Layer

- CLI command dispatch (`stdin/stdout`)
- HTTP/JSON APIs (`backend/src/routes`)
- Optional WebSocket/event channels

### 5) Microkernel Layer (Out of Repo Scope)

- CPU scheduling, physical memory management, and interrupt routing remain in host kernel/hypervisor.
- Khy OS integrates with existing Linux/hypervisor stacks for VMware/bare-metal delivery workflows.

## Core Modules

- `khy_quant/cli.py`: Python entrypoint and backend bootstrap handoff.
- `backend/bin/khyquant.js`: Node CLI entry.
- `backend/src/cli/router.js`: command parse + dispatch.
- `backend/src/services/`: domain services and WASM execution host.
- `backend/src/routes/`: HTTP API routes.
- `frontend/src/services/wasm/wasmBridge.js`: browser JS <-> WASM bridge.

## Design Rules

- Keep kernel responsibilities outside business runtime.
- Keep I/O in host layer (CLI/routes/services), not inside WASM modules.
- Keep WASM modules pure, deterministic, and replaceable.
- Keep command and service boundaries explicit and testable.
