System Architecture
How does PotatoOS actually work?
The Four-Layer Stack
PotatoOS operates as a layered system, with each level handling specific responsibilities. Data flows from the user down through STARCH, into Godot, and finally to your host operating system.
-
Host Operating System
The foundation layer — your actual OS (Windows, macOS, or Linux). It handles all the hardware stuff PotatoOS doesn't: device drivers, kernel operations, memory management, and networking. PotatoOS leverages these services without reimplementing them.
-
Godot Runtime
The container that PotatoOS lives in. Godot acts as a virtual kernel, managing graphics rendering, threading, user input, and windowing. It provides the sandboxed environment that makes PotatoOS portable across platforms whilst isolating it from direct hardware access.
-
STARCH Interpreter & Core System
The engine of PotatoOS. This layer includes the STARCH interpreter (built in GDScript/C), core libraries, the window manager, and system APIs. All PotatoOS logic runs here; when you execute a STARCH script, this is where it happens.
-
User Experience Layer
What you actually interact with: the Mash shell (command-line interface), file browser, text editor, and all bundled applications. Everything here is written in STARCH and communicates with the core system through well-defined APIs.
PotatoFS
PotatoFS is the file system that powers PotatoOS. It's located in your program data folder (%APPDATA%\PotatoCorp\PotatoOS\potatofs on Windows or $HOME/PotatoCorp/PotatoOS/potatofs) and contains the files for both the system and user data. It's split up into two directories:
/system
- assets
- app
- bin
- etc
- host
- lib
The system folder contains all system files and is generally read-only.
assetsis used for system assets such as icons.appstores pre-installed and system-wide apps.binhas core essential STARCH scripts and the Mash binary.etcstores configuration files.hoststores binaries for communicating with the host OS.libstores common libraries and modules for STARCH use.
/users
- bob/
- documents/
- downloads/
- media/
- alice/
- documents/
- downloads/
- media/
The users folder contains all user data, split for each user.
[username]is the home directory for the user, and includes user-specific configuration.[username]/documentscan be used for storing documents and code.[username]/downloadsis the default download location.[username]/mediacan be used for storing images and videos.