# vscode-player/phseos architecture

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

- Interactive diagram: https://gitdiagram.com/vscode-player/phseos
- Repository: https://github.com/vscode-player/phseos

## Overview

Phse OS is a Python-based pseudo-OS that models hardware state in JSON files and runs PhseX programs from its simulated disk. The main workflow initializes configured RAM and CPU state, then executes the disk shell: PhseX parses instructions, loads libraries, and dispatches operations that manipulate simulated state or produce output. The README documents configuration and initialization; sampled sources show arithmetic, data operations, file I/O, process requests, and output. Some referenced runtime helpers are absent from the tree, so their internal wiring is not expanded.

Main entry points: [`phsex.py`](https://github.com/vscode-player/phseos/blob/main/phsex.py) (PhseX interpreter), [`init.py`](https://github.com/vscode-player/phseos/blob/main/init.py) (State initializer), [`hardware/DISK/system/phsex/library/stdio/data_op.py`](https://github.com/vscode-player/phseos/blob/main/hardware/DISK/system/phsex/library/stdio/data_op.py) (Data operations), [`hardware/DISK/system/phsex/library/stdio/output_op.py`](https://github.com/vscode-player/phseos/blob/main/hardware/DISK/system/phsex/library/stdio/output_op.py) (Output operations)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_boot["Boot and configuration"]
  node_config["OS configuration<br/>[build.json]"]
  node_init["State initializer<br/>[init.py]"]
  node_starter["OS launcher<br/>[os_start.py]"]
end

subgraph group_runtime["PhseX runtime"]
  node_shell["System shell<br/>[shell.phx]"]
  node_interpreter["PhseX interpreter<br/>[phsex.py]"]
end

subgraph group_state["Simulated hardware and disk"]
  node_ram[("RAM state<br/>[memory.json]")]
  node_ram_status[("RAM allocation state<br/>[status.json]")]
  node_registers[("CPU registers<br/>[register.json]")]
  node_cpu_status[("Register status<br/>[status.json]")]
  node_flags[("CPU flags<br/>[F.json]")]
  node_disk[("Simulated disk")]
  node_charset["Character encoding<br/>[PhseEncode.json]"]
end

subgraph group_libraries["Instruction libraries"]
  node_stdio_package["Standard I/O package<br/>[package.py]"]
  node_data_ops["Data operations<br/>[data_op.py]"]
  node_math_ops["Math operations<br/>[math_op.py]"]
  node_output_ops["Output operations<br/>[output_op.py]"]
  node_file_package["File I/O package<br/>[package.py]"]
  node_file_ops["File operations<br/>[file_op.py]"]
  node_process_package["Process package<br/>[package.py]"]
  node_process_ops["Process requests<br/>[request.py]"]
end

node_user(("User"))
node_console(("Console"))

node_user -->|"starts"| node_starter
node_starter -->|"initializes"| node_init
node_init -->|"reads"| node_config
node_init -->|"initializes"| node_ram
node_init -->|"initializes"| node_ram_status
node_init -->|"initializes"| node_registers
node_init -->|"initializes"| node_cpu_status
node_init -->|"initializes"| node_flags
node_starter -->|"runs"| node_interpreter
node_starter -->|"reads"| node_config
node_interpreter -->|"reads"| node_shell
node_interpreter -->|"reads"| node_config
node_interpreter -->|"loads on demand"| node_stdio_package
node_interpreter -->|"loads on demand"| node_file_package
node_interpreter -->|"loads on demand"| node_process_package
node_stdio_package -->|"exports"| node_data_ops
node_stdio_package -->|"exports"| node_math_ops
node_stdio_package -->|"exports"| node_output_ops
node_file_package -->|"exports"| node_file_ops
node_process_package -->|"exports"| node_process_ops
node_interpreter -->|"dispatches"| node_data_ops
node_interpreter -->|"dispatches"| node_math_ops
node_interpreter -->|"dispatches"| node_output_ops
node_interpreter -->|"dispatches"| node_file_ops
node_interpreter -->|"dispatches"| node_process_ops
node_data_ops -->|"reads and writes"| node_ram
node_data_ops -->|"reads and writes"| node_registers
node_data_ops -->|"checks allocation"| node_ram_status
node_data_ops -->|"checks allocation"| node_cpu_status
node_data_ops -->|"reads and writes"| node_flags
node_math_ops -->|"reads and writes"| node_ram
node_math_ops -->|"reads and writes"| node_registers
node_output_ops -->|"reads"| node_ram
node_output_ops -->|"reads"| node_registers
node_output_ops -->|"loads encoding"| node_charset
node_output_ops -->|"prints"| node_console
node_file_ops -->|"reads and writes"| node_disk
node_process_ops -->|"updates process state"| node_interpreter

click node_config "https://github.com/vscode-player/phseos/blob/main/build.json"
click node_init "https://github.com/vscode-player/phseos/blob/main/init.py"
click node_starter "https://github.com/vscode-player/phseos/blob/main/os_start.py"
click node_shell "https://github.com/vscode-player/phseos/blob/main/hardware/DISK/system/shell.phx"
click node_interpreter "https://github.com/vscode-player/phseos/blob/main/phsex.py"
click node_ram "https://github.com/vscode-player/phseos/blob/main/hardware/RAM/memory.json"
click node_ram_status "https://github.com/vscode-player/phseos/blob/main/hardware/RAM/status.json"
click node_registers "https://github.com/vscode-player/phseos/blob/main/hardware/CPU/register.json"
click node_cpu_status "https://github.com/vscode-player/phseos/blob/main/hardware/CPU/status.json"
click node_flags "https://github.com/vscode-player/phseos/blob/main/hardware/CPU/F.json"
click node_disk "https://github.com/vscode-player/phseos/tree/main/hardware/DISK"
click node_stdio_package "https://github.com/vscode-player/phseos/blob/main/hardware/DISK/system/phsex/library/stdio/package.py"
click node_data_ops "https://github.com/vscode-player/phseos/blob/main/hardware/DISK/system/phsex/library/stdio/data_op.py"
click node_math_ops "https://github.com/vscode-player/phseos/blob/main/hardware/DISK/system/phsex/library/stdio/math_op.py"
click node_output_ops "https://github.com/vscode-player/phseos/blob/main/hardware/DISK/system/phsex/library/stdio/output_op.py"
click node_file_package "https://github.com/vscode-player/phseos/blob/main/hardware/DISK/system/phsex/library/FileIO/package.py"
click node_file_ops "https://github.com/vscode-player/phseos/blob/main/hardware/DISK/system/phsex/library/FileIO/file_op.py"
click node_process_package "https://github.com/vscode-player/phseos/blob/main/hardware/DISK/system/phsex/library/Process/package.py"
click node_process_ops "https://github.com/vscode-player/phseos/blob/main/hardware/DISK/system/phsex/library/Process/request.py"
click node_charset "https://github.com/vscode-player/phseos/blob/main/hardware/DISK/system/CharSet/PhseEncode.json"

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_config,node_init,node_starter,node_user toneBlue
class node_shell,node_interpreter toneAmber
class node_ram,node_ram_status,node_registers,node_cpu_status,node_flags,node_disk,node_charset toneMint
class node_stdio_package,node_data_ops,node_math_ops,node_output_ops,node_file_package,node_file_ops,node_process_package,node_process_ops toneRose
class node_console toneIndigo
```

## Components

### Boot and configuration

- [OS configuration](https://github.com/vscode-player/phseos/blob/main/build.json): `build.json`
- [State initializer](https://github.com/vscode-player/phseos/blob/main/init.py): `init.py`
- [OS launcher](https://github.com/vscode-player/phseos/blob/main/os_start.py): `os_start.py`

### PhseX runtime

- [System shell](https://github.com/vscode-player/phseos/blob/main/hardware/DISK/system/shell.phx): `hardware/DISK/system/shell.phx`
- [PhseX interpreter](https://github.com/vscode-player/phseos/blob/main/phsex.py): `phsex.py`

### Simulated hardware and disk

- [RAM state](https://github.com/vscode-player/phseos/blob/main/hardware/RAM/memory.json): `hardware/RAM/memory.json`
- [RAM allocation state](https://github.com/vscode-player/phseos/blob/main/hardware/RAM/status.json): `hardware/RAM/status.json`
- [CPU registers](https://github.com/vscode-player/phseos/blob/main/hardware/CPU/register.json): `hardware/CPU/register.json`
- [Register status](https://github.com/vscode-player/phseos/blob/main/hardware/CPU/status.json): `hardware/CPU/status.json`
- [CPU flags](https://github.com/vscode-player/phseos/blob/main/hardware/CPU/F.json): `hardware/CPU/F.json`
- [Simulated disk](https://github.com/vscode-player/phseos/tree/main/hardware/DISK): `hardware/DISK`
- [Character encoding](https://github.com/vscode-player/phseos/blob/main/hardware/DISK/system/CharSet/PhseEncode.json): `hardware/DISK/system/CharSet/PhseEncode.json`

### Instruction libraries

- [Standard I/O package](https://github.com/vscode-player/phseos/blob/main/hardware/DISK/system/phsex/library/stdio/package.py): `hardware/DISK/system/phsex/library/stdio/package.py`
- [Data operations](https://github.com/vscode-player/phseos/blob/main/hardware/DISK/system/phsex/library/stdio/data_op.py): `hardware/DISK/system/phsex/library/stdio/data_op.py`
- [Math operations](https://github.com/vscode-player/phseos/blob/main/hardware/DISK/system/phsex/library/stdio/math_op.py): `hardware/DISK/system/phsex/library/stdio/math_op.py`
- [Output operations](https://github.com/vscode-player/phseos/blob/main/hardware/DISK/system/phsex/library/stdio/output_op.py): `hardware/DISK/system/phsex/library/stdio/output_op.py`
- [File I/O package](https://github.com/vscode-player/phseos/blob/main/hardware/DISK/system/phsex/library/FileIO/package.py): `hardware/DISK/system/phsex/library/FileIO/package.py`
- [File operations](https://github.com/vscode-player/phseos/blob/main/hardware/DISK/system/phsex/library/FileIO/file_op.py): `hardware/DISK/system/phsex/library/FileIO/file_op.py`
- [Process package](https://github.com/vscode-player/phseos/blob/main/hardware/DISK/system/phsex/library/Process/package.py): `hardware/DISK/system/phsex/library/Process/package.py`
- [Process requests](https://github.com/vscode-player/phseos/blob/main/hardware/DISK/system/phsex/library/Process/request.py): `hardware/DISK/system/phsex/library/Process/request.py`

### Other components

- **User**
- **Console**

## Connections

- User → OS launcher: starts
- OS launcher → State initializer: initializes
- State initializer → OS configuration: reads
- State initializer → RAM state: initializes
- State initializer → RAM allocation state: initializes
- State initializer → CPU registers: initializes
- State initializer → Register status: initializes
- State initializer → CPU flags: initializes
- OS launcher → PhseX interpreter: runs
- OS launcher → OS configuration: reads
- PhseX interpreter → System shell: reads
- PhseX interpreter → OS configuration: reads
- PhseX interpreter → Standard I/O package: loads on demand
- PhseX interpreter → File I/O package: loads on demand
- PhseX interpreter → Process package: loads on demand
- Standard I/O package → Data operations: exports
- Standard I/O package → Math operations: exports
- Standard I/O package → Output operations: exports
- File I/O package → File operations: exports
- Process package → Process requests: exports
- PhseX interpreter → Data operations: dispatches
- PhseX interpreter → Math operations: dispatches
- PhseX interpreter → Output operations: dispatches
- PhseX interpreter → File operations: dispatches
- PhseX interpreter → Process requests: dispatches
- Data operations → RAM state: reads and writes
- Data operations → CPU registers: reads and writes
- Data operations → RAM allocation state: checks allocation
- Data operations → Register status: checks allocation
- Data operations → CPU flags: reads and writes
- Math operations → RAM state: reads and writes
- Math operations → CPU registers: reads and writes
- Output operations → RAM state: reads
- Output operations → CPU registers: reads
- Output operations → Character encoding: loads encoding
- Output operations → Console: prints
- File operations → Simulated disk: reads and writes
- Process requests → PhseX interpreter: updates process state