# ish-app/ish architecture

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

- Interactive diagram: https://gitdiagram.com/ish-app/ish
- Repository: https://github.com/ish-app/ish

## Overview

iSH is an iOS Linux shell: it runs Linux userspace programs through x86 user-mode emulation and translates their system calls. The principal workflow is launching a shell, executing instructions, and servicing its system calls through process, memory, and filesystem facilities, with filesystem and terminal behavior producing user-visible results. The README also describes an optimized threaded-code interpreter and command-line debugging. Several implementation links and iOS view relationships are not established by the sampled excerpts or README, so those are omitted rather than inferred.

Main entry points: [`main.c`](https://github.com/ish-app/ish/blob/master/main.c) (Runtime entry), [`kernel/task.h`](https://github.com/ish-app/ish/blob/master/kernel/task.h) (Process and tasks), [`kernel/calls.h`](https://github.com/ish-app/ish/blob/master/kernel/calls.h) (Syscall interface), [`kernel/fs.c`](https://github.com/ish-app/ish/blob/master/kernel/fs.c) (Filesystem syscalls)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["iOS shell"]
  node_ios_ui["iOS app UI"]
  node_terminal_ui["Terminal UI"]
  node_terminal_js["Terminal frontend<br/>[term.js]"]
end

subgraph group_runtime["Execution runtime"]
  node_entry["Runtime entry<br/>[main.c]"]
  node_runtime_setup["Runtime setup<br/>[xX_main_Xx.h]"]
  node_cpu_decode["x86 decoder<br/>[decode.h]"]
  node_threaded_interpreter["Threaded interpreter<br/>[gen.c]"]
  node_cpu_state["CPU state<br/>[cpu.h]"]
end

subgraph group_kernel["Linux compatibility"]
  node_syscall_api["Syscall interface<br/>[calls.h]"]
  node_processes["Process and tasks<br/>[task.h]"]
  node_memory["Virtual memory<br/>[memory.h]"]
  node_fs_syscalls["Filesystem syscalls<br/>[fs.c]"]
  node_fd_layer["File descriptors<br/>[fd.h]"]
  node_filesystem["Filesystem backends"]
  node_procfs["Process filesystem<br/>[pid.c]"]
  node_sockets["Socket operations<br/>[sock.c]"]
  node_signals["Signal handling<br/>[signal.c]"]
end

subgraph group_support["Runtime support"]
  node_platform["Platform interface<br/>[platform.h]"]
  node_sync["Synchronization<br/>[sync.h]"]
end

node_user(("Shell user"))
node_host(("Host OS"))

node_user -.->|"uses"| node_ios_ui
node_ios_ui -.->|"presents"| node_terminal_ui
node_terminal_ui -.->|"uses"| node_terminal_js
node_entry -->|"emulates x86"| node_cpu_decode
node_entry -->|"translates syscalls"| node_syscall_api
node_entry -.->|"initializes"| node_runtime_setup
node_cpu_decode -->|"interprets"| node_cpu_state
node_threaded_interpreter -.->|"executes state"| node_cpu_state
node_syscall_api -->|"uses task state"| node_processes
node_syscall_api -.->|"dispatches filesystem calls"| node_fs_syscalls
node_fs_syscalls -->|"uses descriptors"| node_fd_layer
node_fs_syscalls -.->|"routes operations"| node_filesystem
node_procfs -->|"reads task state"| node_processes
node_sockets -->|"uses descriptors"| node_fd_layer
node_processes -->|"tracks address space"| node_memory
node_signals -->|"uses task state"| node_processes
node_runtime_setup -.->|"configures runtime filesystems"| node_filesystem
node_entry -.->|"runs on"| node_platform
node_filesystem -.->|"accesses host facilities"| node_host

click node_ios_ui "https://github.com/ish-app/ish/tree/master/app"
click node_terminal_ui "https://github.com/ish-app/ish/blob/master/app/TerminalViewController.h"
click node_terminal_js "https://github.com/ish-app/ish/blob/master/app/terminal/term.js"
click node_entry "https://github.com/ish-app/ish/blob/master/main.c"
click node_runtime_setup "https://github.com/ish-app/ish/blob/master/xX_main_Xx.h"
click node_cpu_decode "https://github.com/ish-app/ish/blob/master/emu/decode.h"
click node_threaded_interpreter "https://github.com/ish-app/ish/blob/master/asbestos/gen.c"
click node_cpu_state "https://github.com/ish-app/ish/blob/master/emu/cpu.h"
click node_syscall_api "https://github.com/ish-app/ish/blob/master/kernel/calls.h"
click node_processes "https://github.com/ish-app/ish/blob/master/kernel/task.h"
click node_memory "https://github.com/ish-app/ish/blob/master/kernel/memory.h"
click node_fs_syscalls "https://github.com/ish-app/ish/blob/master/kernel/fs.c"
click node_fd_layer "https://github.com/ish-app/ish/blob/master/fs/fd.h"
click node_filesystem "https://github.com/ish-app/ish/tree/master/fs"
click node_procfs "https://github.com/ish-app/ish/blob/master/fs/proc/pid.c"
click node_sockets "https://github.com/ish-app/ish/blob/master/fs/sock.c"
click node_signals "https://github.com/ish-app/ish/blob/master/kernel/signal.c"
click node_platform "https://github.com/ish-app/ish/blob/master/platform/platform.h"
click node_sync "https://github.com/ish-app/ish/blob/master/util/sync.h"

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_ios_ui,node_terminal_ui,node_terminal_js,node_user toneBlue
class node_entry,node_runtime_setup,node_cpu_decode,node_threaded_interpreter,node_cpu_state toneAmber
class node_syscall_api,node_processes,node_memory,node_fs_syscalls,node_fd_layer,node_filesystem,node_procfs,node_sockets,node_signals toneMint
class node_platform,node_sync toneRose
class node_host toneIndigo
```

## Components

### iOS shell

- [iOS app UI](https://github.com/ish-app/ish/tree/master/app): `app`
- [Terminal UI](https://github.com/ish-app/ish/blob/master/app/TerminalViewController.h): `app/TerminalViewController.h`
- [Terminal frontend](https://github.com/ish-app/ish/blob/master/app/terminal/term.js): `app/terminal/term.js`

### Execution runtime

- [Runtime entry](https://github.com/ish-app/ish/blob/master/main.c): `main.c`
- [Runtime setup](https://github.com/ish-app/ish/blob/master/xX_main_Xx.h): `xX_main_Xx.h`
- [x86 decoder](https://github.com/ish-app/ish/blob/master/emu/decode.h): `emu/decode.h`
- [Threaded interpreter](https://github.com/ish-app/ish/blob/master/asbestos/gen.c): `asbestos/gen.c`
- [CPU state](https://github.com/ish-app/ish/blob/master/emu/cpu.h): `emu/cpu.h`

### Linux compatibility

- [Syscall interface](https://github.com/ish-app/ish/blob/master/kernel/calls.h): `kernel/calls.h`
- [Process and tasks](https://github.com/ish-app/ish/blob/master/kernel/task.h): `kernel/task.h`
- [Virtual memory](https://github.com/ish-app/ish/blob/master/kernel/memory.h): `kernel/memory.h`
- [Filesystem syscalls](https://github.com/ish-app/ish/blob/master/kernel/fs.c): `kernel/fs.c`
- [File descriptors](https://github.com/ish-app/ish/blob/master/fs/fd.h): `fs/fd.h`
- [Filesystem backends](https://github.com/ish-app/ish/tree/master/fs): `fs`
- [Process filesystem](https://github.com/ish-app/ish/blob/master/fs/proc/pid.c): `fs/proc/pid.c`
- [Socket operations](https://github.com/ish-app/ish/blob/master/fs/sock.c): `fs/sock.c`
- [Signal handling](https://github.com/ish-app/ish/blob/master/kernel/signal.c): `kernel/signal.c`

### Runtime support

- [Platform interface](https://github.com/ish-app/ish/blob/master/platform/platform.h): `platform/platform.h`
- [Synchronization](https://github.com/ish-app/ish/blob/master/util/sync.h): `util/sync.h`

### Other components

- **Shell user**
- **Host OS**

## Connections

- Shell user → iOS app UI: uses
- iOS app UI → Terminal UI: presents
- Terminal UI → Terminal frontend: uses
- Runtime entry → x86 decoder: emulates x86
- Runtime entry → Syscall interface: translates syscalls (evidence: `main.c`)
- Runtime entry → Runtime setup: initializes (evidence: `main.c`)
- x86 decoder → CPU state: interprets (evidence: `emu/decode.h`)
- Threaded interpreter → CPU state: executes state
- Syscall interface → Process and tasks: uses task state (evidence: `kernel/calls.h`)
- Syscall interface → Filesystem syscalls: dispatches filesystem calls (evidence: `kernel/fs.c`)
- Filesystem syscalls → File descriptors: uses descriptors (evidence: `kernel/fs.c`)
- Filesystem syscalls → Filesystem backends: routes operations (evidence: `kernel/fs.c`)
- Process filesystem → Process and tasks: reads task state (evidence: `fs/proc/pid.c`)
- Socket operations → File descriptors: uses descriptors (evidence: `fs/sock.c`)
- Process and tasks → Virtual memory: tracks address space (evidence: `kernel/task.h`)
- Signal handling → Process and tasks: uses task state (evidence: `kernel/signal.c`)
- Runtime setup → Filesystem backends: configures runtime filesystems (evidence: `xX_main_Xx.h`)
- Runtime entry → Platform interface: runs on
- Filesystem backends → Host OS: accesses host facilities
