---
title: WebGPU OS Architecture
description: The kernel, shell, package system, storage, and drivers — and how an app moves from a folder or .prpkg to a running, capability-gated panel.
updated: 2026-06-12
---

# WebGPU OS Architecture

The kernel, shell, package system, storage, and drivers — and how an app moves from a folder or `.prpkg` to a running, capability-gated panel.

## Layout

```mermaid
flowchart TD
  boot[boot.js / index.js\nbootWebGpuOS] --> kernel[kernel/]
  kernel --> shell[shell/\nDesktop, Taskbar, StartMenu]
  kernel --> packages[packages/\nPackageManager, Loader, Verifier, Update]
  kernel --> storage[storage/\nVirtualFS, OPFS, IndexedDB, Sandbox]
  kernel --> appforge[appforge/\nRegistry, Services, Context, Layout, Factory]
  kernel --> drivers[drivers/\nAudio, Crypto, Net, Profile, WebSurface]
  appforge --> apps
  shell --> apps[apps/\nruntime-discovered]
  packages --> apps
```

## Kernel (`webgpu-os/kernel/`)

The privileged core. Notable components:

- **`KernelBootstrap.js`** — brings up kernel services in order: `TrustStore.init()` → `PackageManager.init()` → `PatchManager` → `UpdateManager`.
- **`Syscalls.js`** — the syscall surface exposed to apps; `guardSyscalls()` wraps them with capability checks; `auditSyscallGuards()` reports coverage. This is a **stable Tier 2 contract**.
- **`AppRegistry.js` / `ModRegistry.js`** — discover apps/mods at runtime.
- **`Permissions.js` / `PermissionPortal.js` / `PermissionStore.js`** — capability resolution, consent UI, persisted grants.
- **`TrustStore.js` / `ProvenanceChecker.js` / `SigningLineage.js`** — trust roots, pinning, provenance.
- **`RuleGraph.js`** — Tier 1 capability-gate stand-in.
- **`SecurityDoctor.js`** — full posture report.
- **GPU mediation:** `GpuDeviceBroker.js`, `GpuInfo.js`, `VRAMTracker.js` (see [GPU Device Sharing](../concepts/gpu-device-sharing.md)).
- **Buses:** `CommandBus.js`, `FxBus.js`, `PatchBus.js`.
- **Surfaces/theme/sound:** `SurfaceManager.js`, `SubsurfaceManager.js`, `ThemeEngine.js`, `UiSounds.js`, `AmbientEngine.js`.
- **Misc:** `VirtualFS.js`, `OsLogger.js`, `ProcessTable.js`, `SessionStore.js`, `SearchManager.js`, `RuntimeModeManager.js`, `net-safety.js`.

## AppForge (`webgpu-os/appforge/`)

AppForge is a modular composition layer over the existing OS. It keeps
`AppRegistry`, `CommandBus`, `Permissions`, `PackageManager`, `PackageHostRealm`,
Desktop, and Plauna panels as the backing runtime, then adds folders for
definitions, registry, tags, scoring, services, context graph, command objects,
layout zones, blueprints, package exports, timeline, lenses, starter packs, and
the visual workspace builder. See [AppForge Contracts](appforge-contracts.md)
for the public API and security invariants.

## Shell (`webgpu-os/shell/`)

The desktop UI, built on Plauna workspaces (every window is a Plauna panel):

- **`Desktop.js`** — the compositor/window manager; `_launchPanel` wraps an app's syscalls with `guardSyscalls`, `_resolveEntryModule` routes `pkg:<id>` entries to the package loader.
- **`Taskbar.js`, `StartMenu.js`, `StatusTray.js`** — shell chrome.
- **`DialogManager.js`, `NotificationCenter.js`** — dialogs + notifications.
- **`PackageHostRealm.js`** — host realm for packaged apps.
- **`WindowSizer.js`, `WindowStateStore.js`, `app-icon.js`** — window sizing/state/icons.

## Packages (`webgpu-os/packages/`)

The `.prpkg` v2 system (encrypted ZIP container + cross-verified public envelope):

```mermaid
flowchart LR
  build[PackageBuilder] --> sign[PackageCrypto\nsign]
  sign --> verify[PackageVerifier\n+ verifyAndAuthorize]
  verify --> install[PackageManager\ninstall]
  install --> load[PackageLoader\npkg:<id> from OPFS]
```

- **`PackageManager.js`** — install/remove/verify/rollback; the `verifyAndAuthorize()` choke point chains integrity → trust → provenance → scan → policy → verdict.
- **`PackageLoader.js`** — loads installed apps from OPFS as a blob-URL module graph (patch-overlay aware).
- **`PackageBuilder/Crypto/Verifier/Scanner/Registry.js`** — build, sign, verify, scan, register.
- **`UpdateManager.js`** — differential updates with anti-rollback + version cooldown.
- **`AppCompiler.js`, `FolderIngestor.js`, `CapabilityMap.js`, `PublisherKeyManager.js`, `Zip.js`, `Gzip.js`** — supporting tools.

See [Security & Trust Model](../concepts/security-model.md) for the trust pipeline.

## Storage (`webgpu-os/storage/`)

Virtual filesystem over browser primitives: `VirtualFS`/`SystemFS` (syscall-facing), `OPFSDriver`, `IndexedDBDriver`, `MountDriver`, `CacheDriver`, `AppSandbox` (per-app isolation), `StorageManager` (orchestration). See [Data Flow](../concepts/data-flow.md).

## Drivers (`webgpu-os/drivers/`)

`AudioDriver`, `CryptoDriver`, `NetDriver`, `ProfileDriver`, `WebSurfaceDriver`. The browser bridge (`browser-bridge/`) and extension (`browser-extension/`) provide native browser integration and an adblock relay.

## The app entry contract

Manifests declare `id`, `name`, `version`, `entry`, `surface`, `permissions`, and `capabilities`. The entry module **default-exports a class with `async mount(root, syscalls)`** (and optional `unmount()`). Dev-tree apps live at `apps/<folder>/manifest.json`; packaged apps embed a `prpkg-v2` manifest and load via `pkg:<id>`. (Source: `webgpu-os/docs/APP_MANIFEST_SPEC.md`.)

## See also

- [Boot Sequence](../concepts/boot-sequence.md)
- [Security & Trust Model](../concepts/security-model.md)
- [App Catalog](app-catalog.md)
- WebGPU OS **API Reference**