# qxii2027/zwebos architecture

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

- Interactive diagram: https://gitdiagram.com/qxii2027/zwebos
- Repository: https://github.com/qxii2027/zwebos

## Overview

WebOS is a macOS-style desktop environment implemented in the browser. Users unlock into a desktop, launch built-in apps, and work with windows and locally persisted OS state; the README highlights window management, a dock/menu bar, and an app ecosystem. The graph preserves those documented capabilities and sampled app/store modules. Several shell and app internals were not excerpted, so documented links use README evidence rather than implying source inspection.

Main entry points: [`src/components/os/DesktopOS.tsx`](https://github.com/qxii2027/zwebos/blob/main/src/components/os/DesktopOS.tsx) (Desktop OS), [`src/lib/os/store.ts`](https://github.com/qxii2027/zwebos/blob/main/src/lib/os/store.ts) (OS state store), [`src/components/os/AppRenderer.tsx`](https://github.com/qxii2027/zwebos/blob/main/src/components/os/AppRenderer.tsx) (App renderer), [`src/components/os/Window.tsx`](https://github.com/qxii2027/zwebos/blob/main/src/components/os/Window.tsx) (Window frame)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Entry and shell"]
  node_desktop["Desktop OS<br/>[DesktopOS.tsx]"]
  node_lock["Lock screen<br/>[LockScreen.tsx]"]
  node_desktopview["Desktop view<br/>[Desktop.tsx]"]
  node_dock["Dock and menu<br/>[Dock.tsx]"]
  node_menubar["Menu bar<br/>[MenuBar.tsx]"]
  node_startmenu["Start menu<br/>[StartMenu.tsx]"]
  node_shortcuts["Global shortcuts"]
end

subgraph group_windows["Window management"]
  node_window["Window frame<br/>[Window.tsx]"]
  node_drag["Drag and resize<br/>[useWindowDrag.ts]"]
  node_switcher["Window switcher<br/>[WindowSwitcher.tsx]"]
  node_taskbar["Taskbar<br/>[Taskbar.tsx]"]
end

subgraph group_apps["Built-in apps"]
  node_appcatalog["App catalog<br/>[defaultApps.ts]"]
  node_appicon["App icons<br/>[AppIcon.tsx]"]
  node_renderer["App renderer<br/>[AppRenderer.tsx]"]
  node_filemanager["File manager<br/>[FileManager.tsx]"]
  node_music["Music player<br/>[MusicPlayer.tsx]"]
  node_clock["Clock tools<br/>[Clock.tsx]"]
  node_otherapps["Other built-in apps"]
end

subgraph group_state["OS state"]
  node_store[("OS state store<br/>[store.ts]")]
  node_types["OS data types<br/>[types.ts]"]
end

node_user(("Browser user"))
node_browserstorage[("Browser local storage")]

node_user -->|"unlocks"| node_lock
node_lock -->|"enters desktop"| node_desktop
node_desktop -.->|"presents"| node_desktopview
node_desktop -->|"provides launch controls"| node_dock
node_desktop -->|"provides controls"| node_menubar
node_desktop -.->|"offers app access"| node_startmenu
node_desktop -.->|"handles shortcuts"| node_shortcuts
node_dock -.->|"displays icons"| node_appicon
node_menubar -->|"uses icons"| node_appicon
node_startmenu -.->|"lists apps"| node_appcatalog
node_desktop -->|"manages windows"| node_window
node_window -.->|"uses gestures"| node_drag
node_window -.->|"renders app"| node_renderer
node_desktop -->|"switches windows"| node_switcher
node_desktop -.->|"tracks windows"| node_taskbar
node_appcatalog -->|"seeds app definitions"| node_store
node_store -->|"uses data types"| node_types
node_store -->|"persists state"| node_browserstorage
node_renderer -.->|"renders app"| node_filemanager
node_renderer -.->|"renders app"| node_music
node_renderer -.->|"renders app"| node_clock
node_renderer -.->|"renders apps"| node_otherapps
node_filemanager -->|"reads and updates files"| node_store
node_music -->|"reads settings and notifies"| node_store
node_clock -->|"uses OS state"| node_store

click node_desktop "https://github.com/qxii2027/zwebos/blob/main/src/components/os/DesktopOS.tsx"
click node_lock "https://github.com/qxii2027/zwebos/blob/main/src/components/os/LockScreen.tsx"
click node_desktopview "https://github.com/qxii2027/zwebos/blob/main/src/components/os/Desktop.tsx"
click node_dock "https://github.com/qxii2027/zwebos/blob/main/src/components/os/Dock.tsx"
click node_menubar "https://github.com/qxii2027/zwebos/blob/main/src/components/os/MenuBar.tsx"
click node_startmenu "https://github.com/qxii2027/zwebos/blob/main/src/components/os/StartMenu.tsx"
click node_shortcuts "https://github.com/qxii2027/zwebos/blob/main/src/components/os/useGlobalShortcuts.ts"
click node_appcatalog "https://github.com/qxii2027/zwebos/blob/main/src/lib/os/defaultApps.ts"
click node_appicon "https://github.com/qxii2027/zwebos/blob/main/src/components/os/AppIcon.tsx"
click node_renderer "https://github.com/qxii2027/zwebos/blob/main/src/components/os/AppRenderer.tsx"
click node_filemanager "https://github.com/qxii2027/zwebos/blob/main/src/components/apps/FileManager.tsx"
click node_music "https://github.com/qxii2027/zwebos/blob/main/src/components/apps/MusicPlayer.tsx"
click node_clock "https://github.com/qxii2027/zwebos/blob/main/src/components/apps/Clock.tsx"
click node_otherapps "https://github.com/qxii2027/zwebos/tree/main/src/components/apps"
click node_window "https://github.com/qxii2027/zwebos/blob/main/src/components/os/Window.tsx"
click node_drag "https://github.com/qxii2027/zwebos/blob/main/src/components/os/useWindowDrag.ts"
click node_switcher "https://github.com/qxii2027/zwebos/blob/main/src/components/os/WindowSwitcher.tsx"
click node_taskbar "https://github.com/qxii2027/zwebos/blob/main/src/components/os/Taskbar.tsx"
click node_store "https://github.com/qxii2027/zwebos/blob/main/src/lib/os/store.ts"
click node_types "https://github.com/qxii2027/zwebos/blob/main/src/lib/os/types.ts"

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_desktop,node_lock,node_desktopview,node_dock,node_menubar,node_startmenu,node_shortcuts,node_user toneBlue
class node_window,node_drag,node_switcher,node_taskbar,node_browserstorage toneAmber
class node_appcatalog,node_appicon,node_renderer,node_filemanager,node_music,node_clock,node_otherapps toneMint
class node_store,node_types toneRose
```

## Components

### Entry and shell

- [Desktop OS](https://github.com/qxii2027/zwebos/blob/main/src/components/os/DesktopOS.tsx): `src/components/os/DesktopOS.tsx`
- [Lock screen](https://github.com/qxii2027/zwebos/blob/main/src/components/os/LockScreen.tsx): `src/components/os/LockScreen.tsx`
- [Desktop view](https://github.com/qxii2027/zwebos/blob/main/src/components/os/Desktop.tsx): `src/components/os/Desktop.tsx`
- [Dock and menu](https://github.com/qxii2027/zwebos/blob/main/src/components/os/Dock.tsx): `src/components/os/Dock.tsx`
- [Menu bar](https://github.com/qxii2027/zwebos/blob/main/src/components/os/MenuBar.tsx): `src/components/os/MenuBar.tsx`
- [Start menu](https://github.com/qxii2027/zwebos/blob/main/src/components/os/StartMenu.tsx): `src/components/os/StartMenu.tsx`
- [Global shortcuts](https://github.com/qxii2027/zwebos/blob/main/src/components/os/useGlobalShortcuts.ts): `src/components/os/useGlobalShortcuts.ts`

### Window management

- [Window frame](https://github.com/qxii2027/zwebos/blob/main/src/components/os/Window.tsx): `src/components/os/Window.tsx`
- [Drag and resize](https://github.com/qxii2027/zwebos/blob/main/src/components/os/useWindowDrag.ts): `src/components/os/useWindowDrag.ts`
- [Window switcher](https://github.com/qxii2027/zwebos/blob/main/src/components/os/WindowSwitcher.tsx): `src/components/os/WindowSwitcher.tsx`
- [Taskbar](https://github.com/qxii2027/zwebos/blob/main/src/components/os/Taskbar.tsx): `src/components/os/Taskbar.tsx`

### Built-in apps

- [App catalog](https://github.com/qxii2027/zwebos/blob/main/src/lib/os/defaultApps.ts): `src/lib/os/defaultApps.ts`
- [App icons](https://github.com/qxii2027/zwebos/blob/main/src/components/os/AppIcon.tsx): `src/components/os/AppIcon.tsx`
- [App renderer](https://github.com/qxii2027/zwebos/blob/main/src/components/os/AppRenderer.tsx): `src/components/os/AppRenderer.tsx`
- [File manager](https://github.com/qxii2027/zwebos/blob/main/src/components/apps/FileManager.tsx): `src/components/apps/FileManager.tsx`
- [Music player](https://github.com/qxii2027/zwebos/blob/main/src/components/apps/MusicPlayer.tsx): `src/components/apps/MusicPlayer.tsx`
- [Clock tools](https://github.com/qxii2027/zwebos/blob/main/src/components/apps/Clock.tsx): `src/components/apps/Clock.tsx`
- [Other built-in apps](https://github.com/qxii2027/zwebos/tree/main/src/components/apps): `src/components/apps`

### OS state

- [OS state store](https://github.com/qxii2027/zwebos/blob/main/src/lib/os/store.ts): `src/lib/os/store.ts`
- [OS data types](https://github.com/qxii2027/zwebos/blob/main/src/lib/os/types.ts): `src/lib/os/types.ts`

### Other components

- **Browser user**
- **Browser local storage**

## Connections

- Browser user → Lock screen: unlocks (evidence: `README.md`)
- Lock screen → Desktop OS: enters desktop (evidence: `README.md`)
- Desktop OS → Desktop view: presents
- Desktop OS → Dock and menu: provides launch controls (evidence: `README.md`)
- Desktop OS → Menu bar: provides controls (evidence: `README.md`)
- Desktop OS → Start menu: offers app access
- Desktop OS → Global shortcuts: handles shortcuts
- Dock and menu → App icons: displays icons
- Menu bar → App icons: uses icons (evidence: `src/components/os/MenuBar.tsx`)
- Start menu → App catalog: lists apps
- Desktop OS → Window frame: manages windows (evidence: `README.md`)
- Window frame → Drag and resize: uses gestures
- Window frame → App renderer: renders app
- Desktop OS → Window switcher: switches windows (evidence: `README.md`)
- Desktop OS → Taskbar: tracks windows
- App catalog → OS state store: seeds app definitions (evidence: `src/lib/os/store.ts`)
- OS state store → OS data types: uses data types (evidence: `src/lib/os/store.ts`)
- OS state store → Browser local storage: persists state (evidence: `src/lib/os/store.ts`)
- App renderer → File manager: renders app
- App renderer → Music player: renders app
- App renderer → Clock tools: renders app
- App renderer → Other built-in apps: renders apps
- File manager → OS state store: reads and updates files (evidence: `src/components/apps/FileManager.tsx`)
- Music player → OS state store: reads settings and notifies (evidence: `src/components/apps/MusicPlayer.tsx`)
- Clock tools → OS state store: uses OS state (evidence: `src/components/apps/Clock.tsx`)
