# jpferreria/styx architecture

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

- Interactive diagram: https://gitdiagram.com/jpferreria/styx
- Repository: https://github.com/jpferreria/styx

## Overview

Styx OS is a browser-native Unix-like desktop and kernel runtime. A user enters commands in the terminal; the shell routes pipelines and scripts to kernel services, which provide process execution, POSIX facilities, and virtual filesystems. The desktop and file finder form a parallel interactive branch, while an optional local LLM server exposes kernel command execution to external clients. The README documents capabilities not present in sampled excerpts; those connections are cited to it, and unsampled implementation details are represented by their exact source paths.

Main entry points: [`packages/shell-ui/src/kernel/index.ts`](https://github.com/jpferreria/styx/blob/main/packages/shell-ui/src/kernel/index.ts) (TypeScript Kernel), [`packages/shell-ui/src/shell/pipeline.ts`](https://github.com/jpferreria/styx/blob/main/packages/shell-ui/src/shell/pipeline.ts) (Command Pipeline), [`packages/shell-ui/src/shell/index.ts`](https://github.com/jpferreria/styx/blob/main/packages/shell-ui/src/shell/index.ts) (Terminal Shell), [`packages/shell-ui/src/main.ts`](https://github.com/jpferreria/styx/blob/main/packages/shell-ui/src/main.ts) (Desktop UI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_desktop["Desktop UI"]
  node_desktop_app["Desktop UI<br/>[main.ts]"]
  node_window_manager["Window Manager<br/>[wm.ts]"]
end

subgraph group_shell["Shell Runtime"]
  node_terminal_shell["Terminal Shell<br/>[index.ts]"]
  node_pipeline["Command Pipeline<br/>[pipeline.ts]"]
  node_script_interpreter["Script Interpreter<br/>[script.ts]"]
end

subgraph group_kernel["Kernel Services"]
  node_kernel_runtime["TypeScript Kernel<br/>[index.ts]"]
  node_wasm_exec["WASI Execution<br/>[execve.ts]"]
  node_wasm_binaries["Wasm Programs<br/>[binaries.ts]"]
  node_process_services["Process Services<br/>[procfs.ts]"]
  node_ipc_signals["IPC and Signals<br/>[signal.ts]"]
  node_security["Security Controls<br/>[acl.ts]"]
  node_networking["Network Sockets<br/>[socket.ts]"]
  node_terminal_sessions["Terminal Sessions<br/>[tmux.ts]"]
  node_dynamic_linker["Wasm Linker<br/>[shlib.ts]"]
end

subgraph group_storage["Storage"]
  node_vfs[("Virtual Filesystem<br/>[index.ts]")]
  node_ext4[("EXT4 Block Storage<br/>[ext4.ts]")]
  node_procfs_sysfs[("Proc and Sys Filesystems<br/>[procfs.ts]")]
end

subgraph group_integration["External Integrations"]
  node_llm_server["LLM Agent Server<br/>[llm-server.ts]"]
  node_llm_sandbox["Code Sandbox<br/>[sandbox.ts]"]
end

node_user(("User"))
node_opfs[("Browser OPFS")]
node_ai_clients(("AI API Clients"))

node_user -->|"opens desktop"| node_desktop_app
node_desktop_app -->|"starts shell"| node_terminal_shell
node_desktop_app -->|"initializes"| node_window_manager
node_user -->|"enters commands"| node_terminal_shell
node_terminal_shell -->|"dispatches commands"| node_pipeline
node_pipeline -->|"runs scripts"| node_script_interpreter
node_terminal_shell -->|"uses kernel"| node_kernel_runtime
node_pipeline -->|"invokes syscalls"| node_kernel_runtime
node_kernel_runtime -->|"executes Wasm"| node_wasm_exec
node_kernel_runtime -->|"installs programs"| node_wasm_binaries
node_pipeline -->|"reads process data"| node_process_services
node_kernel_runtime -.->|"provides IPC"| node_ipc_signals
node_kernel_runtime -.->|"enforces controls"| node_security
node_kernel_runtime -.->|"provides sockets"| node_networking
node_kernel_runtime -.->|"provides sessions"| node_terminal_sessions
node_wasm_exec -.->|"loads libraries"| node_dynamic_linker
node_kernel_runtime -->|"serves file operations"| node_vfs
node_kernel_runtime -.->|"mounts block storage"| node_ext4
node_kernel_runtime -.->|"exposes system files"| node_procfs_sysfs
node_ext4 -.->|"persists blocks"| node_opfs
node_ai_clients -.->|"sends API requests"| node_llm_server
node_llm_server -.->|"dispatches tool calls"| node_llm_sandbox
node_llm_server -.->|"runs commands"| node_kernel_runtime

click node_desktop_app "https://github.com/jpferreria/styx/blob/main/packages/shell-ui/src/main.ts"
click node_window_manager "https://github.com/jpferreria/styx/blob/main/packages/shell-ui/src/shell/wm.ts"
click node_terminal_shell "https://github.com/jpferreria/styx/blob/main/packages/shell-ui/src/shell/index.ts"
click node_pipeline "https://github.com/jpferreria/styx/blob/main/packages/shell-ui/src/shell/pipeline.ts"
click node_script_interpreter "https://github.com/jpferreria/styx/blob/main/packages/shell-ui/src/shell/script.ts"
click node_kernel_runtime "https://github.com/jpferreria/styx/blob/main/packages/shell-ui/src/kernel/index.ts"
click node_wasm_exec "https://github.com/jpferreria/styx/blob/main/packages/shell-ui/src/kernel/execve.ts"
click node_wasm_binaries "https://github.com/jpferreria/styx/blob/main/packages/shell-ui/src/kernel/binaries.ts"
click node_process_services "https://github.com/jpferreria/styx/blob/main/packages/shell-ui/src/kernel/procfs.ts"
click node_ipc_signals "https://github.com/jpferreria/styx/blob/main/packages/shell-ui/src/kernel/signal.ts"
click node_security "https://github.com/jpferreria/styx/blob/main/packages/shell-ui/src/kernel/acl.ts"
click node_networking "https://github.com/jpferreria/styx/blob/main/packages/shell-ui/src/kernel/socket.ts"
click node_terminal_sessions "https://github.com/jpferreria/styx/blob/main/packages/shell-ui/src/kernel/tmux.ts"
click node_dynamic_linker "https://github.com/jpferreria/styx/blob/main/packages/shell-ui/src/kernel/shlib.ts"
click node_llm_server "https://github.com/jpferreria/styx/blob/main/packages/shell-ui/src/kernel/llm-server.ts"
click node_llm_sandbox "https://github.com/jpferreria/styx/blob/main/packages/shell-ui/src/kernel/sandbox.ts"
click node_vfs "https://github.com/jpferreria/styx/blob/main/packages/shell-ui/src/kernel/index.ts"
click node_ext4 "https://github.com/jpferreria/styx/blob/main/packages/shell-ui/src/kernel/ext4.ts"
click node_procfs_sysfs "https://github.com/jpferreria/styx/blob/main/packages/shell-ui/src/kernel/procfs.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_app,node_window_manager,node_user,node_ai_clients toneBlue
class node_terminal_shell,node_pipeline,node_script_interpreter,node_opfs toneAmber
class node_kernel_runtime,node_wasm_exec,node_wasm_binaries,node_process_services,node_ipc_signals,node_security,node_networking,node_terminal_sessions,node_dynamic_linker toneMint
class node_vfs,node_ext4,node_procfs_sysfs toneRose
class node_llm_server,node_llm_sandbox toneIndigo
```

## Components

### Desktop UI

- [Desktop UI](https://github.com/jpferreria/styx/blob/main/packages/shell-ui/src/main.ts): `packages/shell-ui/src/main.ts`
- [Window Manager](https://github.com/jpferreria/styx/blob/main/packages/shell-ui/src/shell/wm.ts): `packages/shell-ui/src/shell/wm.ts`

### Shell Runtime

- [Terminal Shell](https://github.com/jpferreria/styx/blob/main/packages/shell-ui/src/shell/index.ts): `packages/shell-ui/src/shell/index.ts`
- [Command Pipeline](https://github.com/jpferreria/styx/blob/main/packages/shell-ui/src/shell/pipeline.ts): `packages/shell-ui/src/shell/pipeline.ts`
- [Script Interpreter](https://github.com/jpferreria/styx/blob/main/packages/shell-ui/src/shell/script.ts): `packages/shell-ui/src/shell/script.ts`

### Kernel Services

- [TypeScript Kernel](https://github.com/jpferreria/styx/blob/main/packages/shell-ui/src/kernel/index.ts): `packages/shell-ui/src/kernel/index.ts`
- [WASI Execution](https://github.com/jpferreria/styx/blob/main/packages/shell-ui/src/kernel/execve.ts): `packages/shell-ui/src/kernel/execve.ts`
- [Wasm Programs](https://github.com/jpferreria/styx/blob/main/packages/shell-ui/src/kernel/binaries.ts): `packages/shell-ui/src/kernel/binaries.ts`
- [Process Services](https://github.com/jpferreria/styx/blob/main/packages/shell-ui/src/kernel/procfs.ts): `packages/shell-ui/src/kernel/procfs.ts`
- [IPC and Signals](https://github.com/jpferreria/styx/blob/main/packages/shell-ui/src/kernel/signal.ts): `packages/shell-ui/src/kernel/signal.ts`
- [Security Controls](https://github.com/jpferreria/styx/blob/main/packages/shell-ui/src/kernel/acl.ts): `packages/shell-ui/src/kernel/acl.ts`
- [Network Sockets](https://github.com/jpferreria/styx/blob/main/packages/shell-ui/src/kernel/socket.ts): `packages/shell-ui/src/kernel/socket.ts`
- [Terminal Sessions](https://github.com/jpferreria/styx/blob/main/packages/shell-ui/src/kernel/tmux.ts): `packages/shell-ui/src/kernel/tmux.ts`
- [Wasm Linker](https://github.com/jpferreria/styx/blob/main/packages/shell-ui/src/kernel/shlib.ts): `packages/shell-ui/src/kernel/shlib.ts`

### Storage

- [Virtual Filesystem](https://github.com/jpferreria/styx/blob/main/packages/shell-ui/src/kernel/index.ts): `packages/shell-ui/src/kernel/index.ts`
- [EXT4 Block Storage](https://github.com/jpferreria/styx/blob/main/packages/shell-ui/src/kernel/ext4.ts): `packages/shell-ui/src/kernel/ext4.ts`
- [Proc and Sys Filesystems](https://github.com/jpferreria/styx/blob/main/packages/shell-ui/src/kernel/procfs.ts): `packages/shell-ui/src/kernel/procfs.ts`

### External Integrations

- [LLM Agent Server](https://github.com/jpferreria/styx/blob/main/packages/shell-ui/src/kernel/llm-server.ts): `packages/shell-ui/src/kernel/llm-server.ts`
- [Code Sandbox](https://github.com/jpferreria/styx/blob/main/packages/shell-ui/src/kernel/sandbox.ts): `packages/shell-ui/src/kernel/sandbox.ts`

### Other components

- **User**
- **Browser OPFS**
- **AI API Clients**

## Connections

- User → Desktop UI: opens desktop
- Desktop UI → Terminal Shell: starts shell (evidence: `packages/shell-ui/src/main.ts`)
- Desktop UI → Window Manager: initializes (evidence: `packages/shell-ui/src/main.ts`)
- User → Terminal Shell: enters commands
- Terminal Shell → Command Pipeline: dispatches commands (evidence: `packages/shell-ui/src/shell/index.ts`)
- Command Pipeline → Script Interpreter: runs scripts (evidence: `packages/shell-ui/src/shell/pipeline.ts`)
- Terminal Shell → TypeScript Kernel: uses kernel (evidence: `packages/shell-ui/src/shell/index.ts`)
- Command Pipeline → TypeScript Kernel: invokes syscalls (evidence: `packages/shell-ui/src/shell/pipeline.ts`)
- TypeScript Kernel → WASI Execution: executes Wasm (evidence: `packages/shell-ui/src/kernel/index.ts`)
- TypeScript Kernel → Wasm Programs: installs programs (evidence: `packages/shell-ui/src/kernel/index.ts`)
- Command Pipeline → Process Services: reads process data (evidence: `packages/shell-ui/src/shell/pipeline.ts`)
- TypeScript Kernel → IPC and Signals: provides IPC (evidence: `packages/shell-ui/src/kernel/index.ts`)
- TypeScript Kernel → Security Controls: enforces controls
- TypeScript Kernel → Network Sockets: provides sockets (evidence: `packages/shell-ui/src/kernel/index.ts`)
- TypeScript Kernel → Terminal Sessions: provides sessions
- WASI Execution → Wasm Linker: loads libraries
- TypeScript Kernel → Virtual Filesystem: serves file operations (evidence: `packages/shell-ui/src/kernel/index.ts`)
- TypeScript Kernel → EXT4 Block Storage: mounts block storage
- TypeScript Kernel → Proc and Sys Filesystems: exposes system files (evidence: `packages/shell-ui/src/kernel/index.ts`)
- EXT4 Block Storage → Browser OPFS: persists blocks
- AI API Clients → LLM Agent Server: sends API requests
- LLM Agent Server → Code Sandbox: dispatches tool calls
- LLM Agent Server → TypeScript Kernel: runs commands (evidence: `packages/shell-ui/src/kernel/llm-server.ts`)
