# phreshos/system architecture

> Architecture diagram of the GitHub repository phreshos/system, 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/phreshos/system
- Repository: https://github.com/phreshos/system

## Overview

PhreshOS is a self-hosted system runtime and browser desktop for web-based Programs. The owner signs in through the Desktop; the System maintains authoritative Program and Process state, runs Program endpoints, and mediates their communication and access to system capabilities. The Desktop reflects that state through windows, shell, and appearance controls. The README documents the product-level workflow and capabilities; source excerpts and the SOURCE INDEX support selected internal links, while unsampled subsystems are shown without speculative wiring.

Main entry points: [`source/server/core/link-manager/auth-manager/auth-manager.ts`](https://github.com/phreshos/system/blob/main/source/server/core/link-manager/auth-manager/auth-manager.ts) (Session authorization), [`source/server/core/link-manager/auth-manager/process-manager/process-manager.ts`](https://github.com/phreshos/system/blob/main/source/server/core/link-manager/auth-manager/process-manager/process-manager.ts) (Process management), [`source/client/core/link-manager/auth-manager/auth-manager.ts`](https://github.com/phreshos/system/blob/main/source/client/core/link-manager/auth-manager/auth-manager.ts) (Desktop session state), [`source/server/core/link-manager/auth-manager/program-manager/program-manager.ts`](https://github.com/phreshos/system/blob/main/source/server/core/link-manager/auth-manager/program-manager/program-manager.ts) (Program management)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_system["System runtime"]
  node_server["System entry<br/>[main.ts]"]
  node_gateway["HTTP gateway<br/>[gateway.ts]"]
  node_server_app["Server application<br/>[application.ts]"]
  node_link["Connection links<br/>[link-manager.ts]"]
end

subgraph group_programs["Programs and processes"]
  node_programs["Program management<br/>[program-manager.ts]"]
  node_program["Program definition<br/>[program.ts]"]
  node_processes["Process management<br/>[process-manager.ts]"]
  node_process["Process lifecycle<br/>[process.ts]"]
  node_runtime["Endpoint runtime<br/>[server-runtime.ts]"]
end

subgraph group_access["Identity and capabilities"]
  node_auth["Authentication<br/>[authentication.ts]"]
  node_auth_link["Session authorization<br/>[auth-manager.ts]"]
  node_permissions["Permission control"]
end

subgraph group_desktop["Browser desktop"]
  node_client_app["Desktop application<br/>[application.ts]"]
  node_client_link["Desktop connection<br/>[link-manager.ts]"]
  node_client_auth["Desktop session state<br/>[auth-manager.ts]"]
  node_desktop_host["Program hosting<br/>[host.ts]"]
  node_desktop_view["Desktop shell and windows<br/>[desktop.tsx]"]
  node_window_manager["Window management<br/>[window-manager.ts]"]
  node_appearance["Appearance settings"]
end

subgraph group_shared["Shared services"]
  node_storage["Storage and uploads<br/>[upload-manager.ts]"]
  node_protocol["Program communication<br/>[proxy.ts]"]
  node_logs["System logs<br/>[logs.ts]"]
end

node_owner(("Owner"))
node_browser(("Browser"))

node_owner -->|"uses"| node_browser
node_browser -->|"opens desktop"| node_gateway
node_server -->|"serves"| node_gateway
node_gateway -->|"serves desktop"| node_client_app
node_client_app -->|"connects through"| node_client_link
node_client_link -->|"reaches system"| node_link
node_owner -->|"signs in"| node_auth
node_link -->|"routes authenticated links"| node_auth_link
node_auth_link -->|"authenticates connections"| node_auth
node_auth_link -->|"initializes"| node_programs
node_auth_link -->|"initializes"| node_processes
node_auth_link -->|"delegates permission checks"| node_permissions
node_programs -->|"loads definitions"| node_program
node_processes -->|"manages"| node_process
node_process -->|"starts endpoint"| node_runtime
node_processes -->|"resolves Program"| node_programs
node_processes -.->|"mediates endpoint communication"| node_protocol
node_auth_link -->|"serves storage access"| node_storage
node_client_link -->|"creates session state"| node_client_auth
node_client_auth -->|"reflects Program state"| node_programs
node_client_auth -->|"reflects Process state"| node_processes
node_desktop_host -->|"hosts client endpoints"| node_client_auth
node_client_auth -->|"provides Process windows"| node_window_manager
node_desktop_view -->|"manages visible windows"| node_window_manager
node_desktop_view -.->|"shows appearance"| node_appearance
node_auth_link -->|"forwards log records"| node_logs

click node_server "https://github.com/phreshos/system/blob/main/source/server/main.ts"
click node_gateway "https://github.com/phreshos/system/blob/main/source/server/view/gateway/gateway.ts"
click node_server_app "https://github.com/phreshos/system/blob/main/source/server/core/application.ts"
click node_link "https://github.com/phreshos/system/blob/main/source/server/core/link-manager/link-manager.ts"
click node_auth "https://github.com/phreshos/system/blob/main/source/server/core/authentication/authentication.ts"
click node_auth_link "https://github.com/phreshos/system/blob/main/source/server/core/link-manager/auth-manager/auth-manager.ts"
click node_programs "https://github.com/phreshos/system/blob/main/source/server/core/link-manager/auth-manager/program-manager/program-manager.ts"
click node_program "https://github.com/phreshos/system/blob/main/source/server/core/link-manager/auth-manager/program-manager/program.ts"
click node_processes "https://github.com/phreshos/system/blob/main/source/server/core/link-manager/auth-manager/process-manager/process-manager.ts"
click node_process "https://github.com/phreshos/system/blob/main/source/server/core/link-manager/auth-manager/process-manager/process.ts"
click node_runtime "https://github.com/phreshos/system/blob/main/source/server/core/server-runtime.ts"
click node_permissions "https://github.com/phreshos/system/blob/main/source/server/core/permission-manager.ts"
click node_storage "https://github.com/phreshos/system/blob/main/source/server/core/upload-manager.ts"
click node_protocol "https://github.com/phreshos/system/blob/main/source/server/core/protocol/proxy.ts"
click node_logs "https://github.com/phreshos/system/blob/main/source/server/core/logs.ts"
click node_client_app "https://github.com/phreshos/system/blob/main/source/client/core/application.ts"
click node_client_link "https://github.com/phreshos/system/blob/main/source/client/core/link-manager/link-manager.ts"
click node_client_auth "https://github.com/phreshos/system/blob/main/source/client/core/link-manager/auth-manager/auth-manager.ts"
click node_desktop_host "https://github.com/phreshos/system/blob/main/source/client/view/components/desktop-host/host.ts"
click node_desktop_view "https://github.com/phreshos/system/blob/main/source/client/view/structure/desktop/desktop.tsx"
click node_window_manager "https://github.com/phreshos/system/blob/main/source/client/view/components/window-manager/window-manager.ts"
click node_appearance "https://github.com/phreshos/system/blob/main/source/server/core/appearance-manager.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_server,node_gateway,node_server_app,node_link,node_browser toneBlue
class node_programs,node_program,node_processes,node_process,node_runtime toneAmber
class node_auth,node_auth_link,node_permissions toneMint
class node_client_app,node_client_link,node_client_auth,node_desktop_host,node_desktop_view,node_window_manager,node_appearance toneRose
class node_storage,node_protocol,node_logs,node_owner toneIndigo
```

## Components

### System runtime

- [System entry](https://github.com/phreshos/system/blob/main/source/server/main.ts): `source/server/main.ts`
- [HTTP gateway](https://github.com/phreshos/system/blob/main/source/server/view/gateway/gateway.ts): `source/server/view/gateway/gateway.ts`
- [Server application](https://github.com/phreshos/system/blob/main/source/server/core/application.ts): `source/server/core/application.ts`
- [Connection links](https://github.com/phreshos/system/blob/main/source/server/core/link-manager/link-manager.ts): `source/server/core/link-manager/link-manager.ts`

### Programs and processes

- [Program management](https://github.com/phreshos/system/blob/main/source/server/core/link-manager/auth-manager/program-manager/program-manager.ts): `source/server/core/link-manager/auth-manager/program-manager/program-manager.ts`
- [Program definition](https://github.com/phreshos/system/blob/main/source/server/core/link-manager/auth-manager/program-manager/program.ts): `source/server/core/link-manager/auth-manager/program-manager/program.ts`
- [Process management](https://github.com/phreshos/system/blob/main/source/server/core/link-manager/auth-manager/process-manager/process-manager.ts): `source/server/core/link-manager/auth-manager/process-manager/process-manager.ts`
- [Process lifecycle](https://github.com/phreshos/system/blob/main/source/server/core/link-manager/auth-manager/process-manager/process.ts): `source/server/core/link-manager/auth-manager/process-manager/process.ts`
- [Endpoint runtime](https://github.com/phreshos/system/blob/main/source/server/core/server-runtime.ts): `source/server/core/server-runtime.ts`

### Identity and capabilities

- [Authentication](https://github.com/phreshos/system/blob/main/source/server/core/authentication/authentication.ts): `source/server/core/authentication/authentication.ts`
- [Session authorization](https://github.com/phreshos/system/blob/main/source/server/core/link-manager/auth-manager/auth-manager.ts): `source/server/core/link-manager/auth-manager/auth-manager.ts`
- [Permission control](https://github.com/phreshos/system/blob/main/source/server/core/permission-manager.ts): `source/server/core/permission-manager.ts`

### Browser desktop

- [Desktop application](https://github.com/phreshos/system/blob/main/source/client/core/application.ts): `source/client/core/application.ts`
- [Desktop connection](https://github.com/phreshos/system/blob/main/source/client/core/link-manager/link-manager.ts): `source/client/core/link-manager/link-manager.ts`
- [Desktop session state](https://github.com/phreshos/system/blob/main/source/client/core/link-manager/auth-manager/auth-manager.ts): `source/client/core/link-manager/auth-manager/auth-manager.ts`
- [Program hosting](https://github.com/phreshos/system/blob/main/source/client/view/components/desktop-host/host.ts): `source/client/view/components/desktop-host/host.ts`
- [Desktop shell and windows](https://github.com/phreshos/system/blob/main/source/client/view/structure/desktop/desktop.tsx): `source/client/view/structure/desktop/desktop.tsx`
- [Window management](https://github.com/phreshos/system/blob/main/source/client/view/components/window-manager/window-manager.ts): `source/client/view/components/window-manager/window-manager.ts`
- [Appearance settings](https://github.com/phreshos/system/blob/main/source/server/core/appearance-manager.ts): `source/server/core/appearance-manager.ts`

### Shared services

- [Storage and uploads](https://github.com/phreshos/system/blob/main/source/server/core/upload-manager.ts): `source/server/core/upload-manager.ts`
- [Program communication](https://github.com/phreshos/system/blob/main/source/server/core/protocol/proxy.ts): `source/server/core/protocol/proxy.ts`
- [System logs](https://github.com/phreshos/system/blob/main/source/server/core/logs.ts): `source/server/core/logs.ts`

### Other components

- **Owner**
- **Browser**

## Connections

- Owner → Browser: uses (evidence: `README.md`)
- Browser → HTTP gateway: opens desktop (evidence: `README.md`)
- System entry → HTTP gateway: serves (evidence: `source/server/main.ts`)
- HTTP gateway → Desktop application: serves desktop (evidence: `README.md`)
- Desktop application → Desktop connection: connects through (evidence: `source/client/core/application.ts`)
- Desktop connection → Connection links: reaches system (evidence: `README.md`)
- Owner → Authentication: signs in (evidence: `README.md`)
- Connection links → Session authorization: routes authenticated links (evidence: `source/server/core/link-manager/link-manager.ts`)
- Session authorization → Authentication: authenticates connections (evidence: `source/server/core/link-manager/auth-manager/auth-manager.ts`)
- Session authorization → Program management: initializes (evidence: `source/server/core/link-manager/auth-manager/auth-manager.ts`)
- Session authorization → Process management: initializes (evidence: `source/server/core/link-manager/auth-manager/auth-manager.ts`)
- Session authorization → Permission control: delegates permission checks (evidence: `source/server/core/link-manager/auth-manager/auth-manager.ts`)
- Program management → Program definition: loads definitions (evidence: `source/server/core/link-manager/auth-manager/program-manager/program-manager.ts`)
- Process management → Process lifecycle: manages (evidence: `source/server/core/link-manager/auth-manager/process-manager/process-manager.ts`)
- Process lifecycle → Endpoint runtime: starts endpoint (evidence: `source/server/core/link-manager/auth-manager/process-manager/process.ts`)
- Process management → Program management: resolves Program (evidence: `source/server/core/link-manager/auth-manager/process-manager/process-manager.ts`)
- Process management → Program communication: mediates endpoint communication
- Session authorization → Storage and uploads: serves storage access (evidence: `source/server/core/link-manager/auth-manager/auth-manager.ts`)
- Desktop connection → Desktop session state: creates session state (evidence: `source/client/core/link-manager/link-manager.ts`)
- Desktop session state → Program management: reflects Program state (evidence: `source/client/core/link-manager/auth-manager/auth-manager.ts`)
- Desktop session state → Process management: reflects Process state (evidence: `source/client/core/link-manager/auth-manager/auth-manager.ts`)
- Program hosting → Desktop session state: hosts client endpoints
- Desktop session state → Window management: provides Process windows (evidence: `source/client/view/components/window-manager/window-manager.ts`)
- Desktop shell and windows → Window management: manages visible windows (evidence: `source/client/view/components/window-manager/window-manager.ts`)
- Desktop shell and windows → Appearance settings: shows appearance
- Session authorization → System logs: forwards log records (evidence: `source/server/core/link-manager/auth-manager/auth-manager.ts`)
