How nihalawasthi/zynqos works
1. Overall shape
- ZynqOS is a browser-hosted micro-OS: a React/TypeScript desktop shell that launches sandboxed apps inside movable windows.
- The repo is split into a client-side desktop, a small serverless backend, a separate Python runtime service, and Rust/WASM binaries.
2. Desktop shell and windowing
- The core UI lives under src/components and src/App.tsx.
- WindowManager, Window, Taskbar, StartMenu, snap/tiling helpers, and shared-window utilities form the shell that owns window lifecycle, focus, snapping, multi-window state, and cross-window coordination.
3. App model
- Individual desktop apps live under src/apps/* and are mounted by the shell rather than routed as a conventional web app.
- Main apps include File Browser, Text Editor, Calculator, Terminal, Settings, Package Importer, Python, Store, and the zynqchat app.
- Some apps are pure React UIs; others delegate work to WASM modules, the VFS, or sync/auth services.
4. Virtual file system as the primary data plane
- src/vfs provides the browser-persistent file system backed by IndexedDB.
- File Browser and Text Editor are direct VFS clients; Terminal, Python, and package import flows also read/write through this layer.
- src/vfs/init.ts seeds default files, and the VFS is the main boundary between user-facing apps and persisted state.
5. WASM/WASI execution boundary
- src/wasm contains loaders for two execution styles:
- wasm-bindgen modules for UI-integrated computation, such as Calculator.
- WASI modules for command-line binaries, such as the Terminal shell and utility commands.
- Built artifacts are served from public/apps/wasm, and the Rust project in apps/terminal-wasi is one of the WASI binaries.
- WASI programs interact with the mounted VFS, so file changes made in the terminal are reflected back into the browser-side storage.
6. Terminal and command execution
- src/apps/terminal is the user-facing command runner.
- It dispatches run/upload-style commands to the WASI loader, and also bridges to Python execution.
- The terminal is therefore the main orchestration surface for non-UI workloads: shell commands, utility binaries, and Python scripts.
7. Python execution path
- Python is supported through a browser-side Pyodide path and a separate remote Python client/service path under src/remotePython and server/py-runtime.
- This makes Python a distinct execution subsystem from WASI: it can run in-browser for lightweight usage or on the dedicated Python runtime service when needed.
- The Python layer is also wired into the VFS so scripts can read/write the same persisted files as the rest of the desktop.
8. Sync, storage, and external backends
- src/storage and src/utils/githubApi.ts implement the persistence/synchronization layer.
- The architecture is hybrid: minimal state is kept on the app server, while user data can sync to user-owned GitHub repositories and optionally Google Drive.
- Consent, provider selection, and sync coordination are handled on the client, with storage adapters abstracting the external targets.
9. Serverless API boundary
- The api/ folder holds backend endpoints such as OAuth callbacks, GitHub app flow, session handling, DB initialization, user-data, chat DB, and cron reset.
- These functions appear to be the minimal trusted server surface: identity, preferences, activity tracking, and scheduled reset logic.
- The README emphasizes that most user files and app data are not stored centrally, but in user-controlled storage.
10. Identity and auth
- src/auth handles OAuth flows, PKCE, quiet auth, and provider-specific integration for GitHub and Google.
- Authentication feeds the sync system and possibly app-specific capabilities like GitHub-backed storage and repo import/export.
- The client-side auth layer is separate from the serverless callbacks, which complete the OAuth round trip.
11. Package system and app distribution
- src/packages plus the .mapp importer implement the package registry/validation/management flow.
- Packages are likely the unit of app distribution and installation inside the desktop, with manifests and examples under public/apps/store-manifest.json and src/packages/examples.ts.
- This is a distinct distribution boundary from the core shell: packages are imported, validated, then mounted or exposed through the launcher/store UI.
12. Chat and realtime subsystem
- src/apps/zynqchat plus shared realtime/storage/crypto utilities suggest an encrypted, synchronized chat feature.
- Its code is isolated from the general desktop apps and likely relies on the same auth/storage infrastructure, but with its own API and realtime channel.
- If diagramming the repo, treat this as a separate feature subsystem rather than part of the shell itself.
13. Build and deployment topology
- The frontend is built with Vite/TypeScript/Tailwind, while Rust WASM modules are compiled separately via the scripts and GitHub Actions workflow.
- server/py-runtime is containerized with Docker, indicating an independently deployable Python service.
- The repo therefore has three deployment concerns: browser client, serverless API, and optional containerized Python runtime, plus build artifacts served as static WASM assets.
Main entry points: WindowManager.tsx Window Manager · fs.ts Virtual FS · terminal/ui.tsx Terminal · python/ui.tsx Python App
Components 24
Browser Client
React/TypeScript desktop shell and bundled apps
- Desktop Shell · Main app entry that mounts the desktop experience
src/App.tsx - Window Manager · Owns window lifecycle, focus, and shared window state
src/components/WindowManager.tsx - Taskbar · Start menu, taskbar, and desktop controls
src/components/Taskbar.tsx - Window UI · Movable window container used by desktop apps
src/components/Window.tsx - File Browser · Browse and manage files in the browser filesystem
src/apps/file-browser/ui.tsx - Text Editor · Edit text files stored in the virtual filesystem
src/apps/text-editor/ui.tsx - Terminal · Runs shell commands, uploads, and Python bridges
src/apps/terminal/ui.tsx - Python App · User-facing Python execution surface
src/apps/python/ui.tsx - Settings · Configures desktop and account preferences
src/apps/settings/ui.tsx - Store · Discover and install packages for the desktop
src/apps/store/ui.tsx - ZynqChat · Encrypted chat feature with its own storage and realtime flow
src/apps/zynqchat/ui.tsx
Execution Runtimes
WASM, Pyodide, and remote Python paths
- WASM Loader · Loads wasm-bindgen and WASI modules for the desktop
src/wasm/wasmLoader.ts - Pyodide Loader · Runs lightweight Python in the browser
src/wasm/pyodideLoader.ts - Remote Python · Client for the separate Python runtime service
src/remotePython/index.ts - Terminal WASI · Rust WASI command binary used by the terminal
apps/terminal-wasi/src/main.rs
Data Layer
Virtual filesystem, sync, and package management
- Virtual FS · Browser-persistent filesystem backed by IndexedDB
src/vfs/fs.ts - VFS Init · Seeds default files and initial filesystem state
src/vfs/init.ts - Sync Layer · Coordinates consent and persistence across providers
src/storage/sync.ts - Auth · OAuth, PKCE, and provider-specific sign-in flows
src/auth/init.ts
Backend Services
Serverless APIs and the Python runtime service
- Serverless API · OAuth callbacks, sessions, user data, and cron reset
api/index.ts - Python Runtime · Dedicated remote Python execution service
server/py-runtime/app/main.py - Chat API · Chat database, realtime coordination, and crypto-backed sync
src/apps/zynqchat/chatApi.ts
Distribution
Package registry and import flow
- Package Manager · Validates, stores, and installs desktop packages
src/packages/manager.ts - MAPP Importer · Imports package bundles into the desktop ecosystem
src/apps/mapp-importer/ui.tsx
Connections 33
- Desktop Shell → Window Manager: mounts · Desktop shell delegates window lifecycle to the manager
- Desktop Shell → Taskbar: renders · Shell composes launcher and desktop controls
- Window Manager → Window UI: uses · Manager instantiates and coordinates windows
- Window Manager → Taskbar: updates · Shares app and window state with the taskbar
- Window Manager → ZynqChat: hosts · Desktop apps are mounted inside managed windows
- Window Manager → File Browser: hosts · Desktop apps are mounted inside managed windows
- Window Manager → Text Editor: hosts · Desktop apps are mounted inside managed windows
- Window Manager → Terminal: hosts · Desktop apps are mounted inside managed windows
- Window Manager → Python App: hosts · Desktop apps are mounted inside managed windows
- Window Manager → Settings: hosts · Desktop apps are mounted inside managed windows
- Window Manager → Store: hosts · Desktop apps are mounted inside managed windows
- File Browser → Virtual FS: reads/writes · File browser operates directly on persisted files
- Text Editor → Virtual FS: reads/writes · Editor persists document changes through the VFS
- Terminal → WASM Loader: dispatches · Terminal sends run-style commands to WASI/WASM loaders
- Terminal → Pyodide Loader: executes · Terminal can route Python work through browser Python
- Terminal → Remote Python: bridges · Terminal can forward Python execution to the remote service
- Terminal → Virtual FS: mounts · Shell commands operate on the shared filesystem
- Python App → Pyodide Loader: uses · Python app runs in-browser Python workloads
- Python App → Remote Python: uses · Python app can offload to the remote runtime
- Python App → Virtual FS: reads/writes · Python scripts share the same persisted files
- MAPP Importer → Package Manager: imports · Package importer feeds validated packages into the manager
- Store → Package Manager: manages · Store UI exposes registry and installation flows
- Package Manager → Virtual FS: stores · Package state and installed content are persisted locally
- Sync Layer → Auth: depends on · Sync coordination relies on authenticated providers
- Sync Layer → Serverless API: syncs via · Client sync uses serverless identity and session endpoints
- Auth → Serverless API: callback · OAuth round trips complete through serverless callbacks
- ZynqChat → Chat API: connects · Chat UI talks to dedicated chat backend services
- ZynqChat → Sync Layer: persists via · Chat state reuses the desktop sync/storage layer
- ZynqChat → Auth: authenticates · Chat feature relies on the shared identity layer
- Terminal WASI → WASM Loader: loaded by · Rust WASI binaries are executed through the wasm loader
- Terminal WASI → Virtual FS: accesses · WASI programs operate on the mounted browser filesystem
- Remote Python → Python Runtime: calls · Client delegates remote execution to the Python service
- VFS Init → Virtual FS: seeds · Initialization populates the persistent filesystem