# dzen25/psych-ward-os architecture

> Architecture diagram of the GitHub repository dzen25/psych-ward-os, 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/dzen25/psych-ward-os
- Repository: https://github.com/dzen25/psych-ward-os

## Overview

Psych Ward OS is documented as a seL4-based, event-driven microkernel OS. Its intended user-to-result flow is shell command → rootserver orchestration → isolated service or child process → IPC/VFS/device result, with watchdog recovery for failed services. The README names implementation files such as main.cpp and shell.cpp, but they are absent from the supplied tree; unsampled product components are therefore associated only with the existing user_apps/src directory. The kernel syscall implementation is present, but specific user-OS call relationships are documented rather than verified in its source.

Main entry points: [`user_apps/src`](https://github.com/dzen25/psych-ward-os/tree/main/user_apps/src) (Rootserver), [`kernel/src/api/syscall.c`](https://github.com/dzen25/psych-ward-os/blob/main/kernel/src/api/syscall.c) (Kernel syscalls), [`kernel/src`](https://github.com/dzen25/psych-ward-os/tree/main/kernel/src) (seL4 kernel)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_control["Process control"]
  node_shell["Shell"]
  node_rootserver["Rootserver"]
  node_lifecycle["Process lifecycle"]
  node_watchdog["Watchdog and GC"]
  node_ipc["IPC and pipes"]
end

subgraph group_services["User services"]
  node_uart["UART driver"]
  node_timer["Timer driver"]
  node_network["Network driver"]
end

subgraph group_io["I/O and storage"]
  node_block["Block driver"]
  node_vfs["VFS and FAT32"]
  node_sharedmem["Shared memory"]
  node_ram[("RAM disk")]
end

subgraph group_kernel["seL4 kernel"]
  node_syscalls["Kernel syscalls<br/>[syscall.c]"]
  node_sel4kernel["seL4 kernel"]
end

node_user(("User"))

node_user -->|"enters commands"| node_shell
node_shell -->|"sends requests"| node_rootserver
node_rootserver -->|"manages processes"| node_lifecycle
node_rootserver -->|"recovers services"| node_watchdog
node_rootserver -->|"coordinates IPC"| node_ipc
node_rootserver -->|"spawns driver"| node_uart
node_rootserver -->|"spawns driver"| node_timer
node_rootserver -->|"spawns driver"| node_network
node_rootserver -->|"spawns driver"| node_block
node_shell -->|"resolves paths"| node_vfs
node_vfs -->|"reads storage"| node_block
node_block -->|"transfers sectors"| node_sharedmem
node_vfs -->|"unifies filesystem"| node_ram
node_rootserver -->|"issues system calls"| node_syscalls
node_shell -->|"requests exec and wait"| node_syscalls
node_syscalls -.->|"dispatches calls"| node_sel4kernel
node_network -->|"routes requests"| node_ipc
node_timer -->|"signals events"| node_ipc

click node_shell "https://github.com/dzen25/psych-ward-os/tree/main/user_apps/src"
click node_rootserver "https://github.com/dzen25/psych-ward-os/tree/main/user_apps/src"
click node_lifecycle "https://github.com/dzen25/psych-ward-os/tree/main/user_apps/src"
click node_watchdog "https://github.com/dzen25/psych-ward-os/tree/main/user_apps/src"
click node_ipc "https://github.com/dzen25/psych-ward-os/tree/main/user_apps/src"
click node_uart "https://github.com/dzen25/psych-ward-os/tree/main/user_apps/src"
click node_timer "https://github.com/dzen25/psych-ward-os/tree/main/user_apps/src"
click node_network "https://github.com/dzen25/psych-ward-os/tree/main/user_apps/src"
click node_block "https://github.com/dzen25/psych-ward-os/tree/main/user_apps/src"
click node_vfs "https://github.com/dzen25/psych-ward-os/tree/main/user_apps/src"
click node_sharedmem "https://github.com/dzen25/psych-ward-os/tree/main/user_apps/src"
click node_syscalls "https://github.com/dzen25/psych-ward-os/blob/main/kernel/src/api/syscall.c"
click node_sel4kernel "https://github.com/dzen25/psych-ward-os/tree/main/kernel/src"
click node_ram "https://github.com/dzen25/psych-ward-os/tree/main/user_apps/src"

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_shell,node_rootserver,node_lifecycle,node_watchdog,node_ipc,node_user toneBlue
class node_uart,node_timer,node_network toneAmber
class node_block,node_vfs,node_sharedmem,node_ram toneMint
class node_syscalls,node_sel4kernel toneRose
```

## Components

### Process control

- [Shell](https://github.com/dzen25/psych-ward-os/tree/main/user_apps/src): `user_apps/src`
- [Rootserver](https://github.com/dzen25/psych-ward-os/tree/main/user_apps/src): `user_apps/src`
- [Process lifecycle](https://github.com/dzen25/psych-ward-os/tree/main/user_apps/src): `user_apps/src`
- [Watchdog and GC](https://github.com/dzen25/psych-ward-os/tree/main/user_apps/src): `user_apps/src`
- [IPC and pipes](https://github.com/dzen25/psych-ward-os/tree/main/user_apps/src): `user_apps/src`

### User services

- [UART driver](https://github.com/dzen25/psych-ward-os/tree/main/user_apps/src): `user_apps/src`
- [Timer driver](https://github.com/dzen25/psych-ward-os/tree/main/user_apps/src): `user_apps/src`
- [Network driver](https://github.com/dzen25/psych-ward-os/tree/main/user_apps/src): `user_apps/src`

### I/O and storage

- [Block driver](https://github.com/dzen25/psych-ward-os/tree/main/user_apps/src): `user_apps/src`
- [VFS and FAT32](https://github.com/dzen25/psych-ward-os/tree/main/user_apps/src): `user_apps/src`
- [Shared memory](https://github.com/dzen25/psych-ward-os/tree/main/user_apps/src): `user_apps/src`
- [RAM disk](https://github.com/dzen25/psych-ward-os/tree/main/user_apps/src): `user_apps/src`

### seL4 kernel

- [Kernel syscalls](https://github.com/dzen25/psych-ward-os/blob/main/kernel/src/api/syscall.c): `kernel/src/api/syscall.c`
- [seL4 kernel](https://github.com/dzen25/psych-ward-os/tree/main/kernel/src): `kernel/src`

### Other components

- **User**

## Connections

- User → Shell: enters commands
- Shell → Rootserver: sends requests
- Rootserver → Process lifecycle: manages processes
- Rootserver → Watchdog and GC: recovers services
- Rootserver → IPC and pipes: coordinates IPC
- Rootserver → UART driver: spawns driver
- Rootserver → Timer driver: spawns driver
- Rootserver → Network driver: spawns driver
- Rootserver → Block driver: spawns driver
- Shell → VFS and FAT32: resolves paths
- VFS and FAT32 → Block driver: reads storage
- Block driver → Shared memory: transfers sectors
- VFS and FAT32 → RAM disk: unifies filesystem
- Rootserver → Kernel syscalls: issues system calls
- Shell → Kernel syscalls: requests exec and wait
- Kernel syscalls → seL4 kernel: dispatches calls
- Network driver → IPC and pipes: routes requests
- Timer driver → IPC and pipes: signals events
