# nihalawasthi/zynqos architecture

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

- Interactive diagram: https://gitdiagram.com/nihalawasthi/zynqos
- Repository: https://github.com/nihalawasthi/zynqos

## Overview

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: [`src/components/WindowManager.tsx`](https://github.com/nihalawasthi/zynqos/blob/main/src/components/WindowManager.tsx) (Window Manager), [`src/vfs/fs.ts`](https://github.com/nihalawasthi/zynqos/blob/main/src/vfs/fs.ts) (Virtual FS), [`src/apps/terminal/ui.tsx`](https://github.com/nihalawasthi/zynqos/blob/main/src/apps/terminal/ui.tsx) (Terminal), [`src/apps/python/ui.tsx`](https://github.com/nihalawasthi/zynqos/blob/main/src/apps/python/ui.tsx) (Python App)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Browser Client"]
  node_app["Desktop Shell<br/>React shell<br/>[App.tsx]"]
  node_window_manager["Window Manager<br/>windowing<br/>[WindowManager.tsx]"]
  node_taskbar["Taskbar<br/>launcher UI<br/>[Taskbar.tsx]"]
  node_window["Window UI<br/>window chrome<br/>[Window.tsx]"]
  node_file_browser["File Browser<br/>VFS app<br/>[ui.tsx]"]
  node_text_editor["Text Editor<br/>VFS app<br/>[ui.tsx]"]
  node_terminal["Terminal<br/>command runner<br/>[ui.tsx]"]
  node_python_app["Python App<br/>script runtime UI<br/>[ui.tsx]"]
  node_settings_app["Settings<br/>preferences app<br/>[ui.tsx]"]
  node_store_app["Store<br/>[ui.tsx]"]
  node_chat_app["ZynqChat<br/>chat app<br/>[ui.tsx]"]
end

subgraph group_exec["Execution Runtimes"]
  node_wasm_loader["WASM Loader<br/>execution loader<br/>[wasmLoader.ts]"]
  node_pyodide_loader["Pyodide Loader<br/>python runtime<br/>[pyodideLoader.ts]"]
  node_remote_python["Remote Python<br/>python client<br/>[index.ts]"]
  node_terminal_wasi["Terminal WASI<br/>rust binary<br/>[main.rs]"]
end

subgraph group_data["Data Layer"]
  node_vfs[("Virtual FS<br/>persistent storage<br/>[fs.ts]")]
  node_vfs_init["VFS Init<br/>seeding<br/>[init.ts]"]
  node_sync_layer["Sync Layer<br/>storage sync<br/>[sync.ts]"]
  node_auth["Auth<br/>[init.ts]"]
end

subgraph group_backend["Backend Services"]
  node_api["Serverless API<br/>backend functions<br/>[index.ts]"]
  node_py_runtime["Python Runtime<br/>container service<br/>[main.py]"]
  node_chat_api["Chat API<br/>chat backend<br/>[chatApi.ts]"]
end

subgraph group_packages["Distribution"]
  node_packages_mgr["Package Manager<br/>package system<br/>[manager.ts]"]
  node_mapp_importer["MAPP Importer<br/>import flow<br/>[ui.tsx]"]
end

node_app -->|"mounts"| node_window_manager
node_app -->|"renders"| node_taskbar
node_window_manager -->|"uses"| node_window
node_window_manager -->|"updates"| node_taskbar
node_window_manager -->|"hosts"| node_chat_app
node_window_manager -->|"hosts"| node_file_browser
node_window_manager -->|"hosts"| node_text_editor
node_window_manager -->|"hosts"| node_terminal
node_window_manager -->|"hosts"| node_python_app
node_window_manager -->|"hosts"| node_settings_app
node_window_manager -->|"hosts"| node_store_app
node_file_browser -->|"reads/writes"| node_vfs
node_text_editor -->|"reads/writes"| node_vfs
node_terminal -->|"dispatches"| node_wasm_loader
node_terminal -->|"executes"| node_pyodide_loader
node_terminal -->|"bridges"| node_remote_python
node_terminal -->|"mounts"| node_vfs
node_python_app -->|"uses"| node_pyodide_loader
node_python_app -->|"uses"| node_remote_python
node_python_app -->|"reads/writes"| node_vfs
node_mapp_importer -->|"imports"| node_packages_mgr
node_store_app -->|"manages"| node_packages_mgr
node_packages_mgr -->|"stores"| node_vfs
node_sync_layer -->|"depends on"| node_auth
node_sync_layer -->|"syncs via"| node_api
node_auth -->|"callback"| node_api
node_chat_app -->|"connects"| node_chat_api
node_chat_app -->|"persists via"| node_sync_layer
node_chat_app -->|"authenticates"| node_auth
node_terminal_wasi -->|"loaded by"| node_wasm_loader
node_terminal_wasi -->|"accesses"| node_vfs
node_remote_python -->|"calls"| node_py_runtime
node_vfs_init -->|"seeds"| node_vfs

click node_app "https://github.com/nihalawasthi/zynqos/blob/main/src/App.tsx"
click node_window_manager "https://github.com/nihalawasthi/zynqos/blob/main/src/components/WindowManager.tsx"
click node_taskbar "https://github.com/nihalawasthi/zynqos/blob/main/src/components/Taskbar.tsx"
click node_window "https://github.com/nihalawasthi/zynqos/blob/main/src/components/Window.tsx"
click node_file_browser "https://github.com/nihalawasthi/zynqos/blob/main/src/apps/file-browser/ui.tsx"
click node_text_editor "https://github.com/nihalawasthi/zynqos/blob/main/src/apps/text-editor/ui.tsx"
click node_terminal "https://github.com/nihalawasthi/zynqos/blob/main/src/apps/terminal/ui.tsx"
click node_python_app "https://github.com/nihalawasthi/zynqos/blob/main/src/apps/python/ui.tsx"
click node_settings_app "https://github.com/nihalawasthi/zynqos/blob/main/src/apps/settings/ui.tsx"
click node_store_app "https://github.com/nihalawasthi/zynqos/blob/main/src/apps/store/ui.tsx"
click node_chat_app "https://github.com/nihalawasthi/zynqos/blob/main/src/apps/zynqchat/ui.tsx"
click node_vfs "https://github.com/nihalawasthi/zynqos/blob/main/src/vfs/fs.ts"
click node_vfs_init "https://github.com/nihalawasthi/zynqos/blob/main/src/vfs/init.ts"
click node_packages_mgr "https://github.com/nihalawasthi/zynqos/blob/main/src/packages/manager.ts"
click node_mapp_importer "https://github.com/nihalawasthi/zynqos/blob/main/src/apps/mapp-importer/ui.tsx"
click node_wasm_loader "https://github.com/nihalawasthi/zynqos/blob/main/src/wasm/wasmLoader.ts"
click node_pyodide_loader "https://github.com/nihalawasthi/zynqos/blob/main/src/wasm/pyodideLoader.ts"
click node_remote_python "https://github.com/nihalawasthi/zynqos/blob/main/src/remotePython/index.ts"
click node_terminal_wasi "https://github.com/nihalawasthi/zynqos/blob/main/apps/terminal-wasi/src/main.rs"
click node_sync_layer "https://github.com/nihalawasthi/zynqos/blob/main/src/storage/sync.ts"
click node_auth "https://github.com/nihalawasthi/zynqos/blob/main/src/auth/init.ts"
click node_api "https://github.com/nihalawasthi/zynqos/blob/main/api/index.ts"
click node_py_runtime "https://github.com/nihalawasthi/zynqos/blob/main/server/py-runtime/app/main.py"
click node_chat_api "https://github.com/nihalawasthi/zynqos/blob/main/src/apps/zynqchat/chatApi.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_app,node_window_manager,node_taskbar,node_window,node_file_browser,node_text_editor,node_terminal,node_python_app,node_settings_app,node_store_app,node_chat_app toneBlue
class node_wasm_loader,node_pyodide_loader,node_remote_python,node_terminal_wasi toneAmber
class node_vfs,node_vfs_init,node_sync_layer,node_auth toneMint
class node_api,node_py_runtime,node_chat_api toneRose
class node_packages_mgr,node_mapp_importer toneIndigo
```

## Components

### Browser Client

React/TypeScript desktop shell and bundled apps

- [Desktop Shell](https://github.com/nihalawasthi/zynqos/blob/main/src/App.tsx): React shell · Main app entry that mounts the desktop experience · `src/App.tsx`
- [Window Manager](https://github.com/nihalawasthi/zynqos/blob/main/src/components/WindowManager.tsx): windowing · Owns window lifecycle, focus, and shared window state · `src/components/WindowManager.tsx`
- [Taskbar](https://github.com/nihalawasthi/zynqos/blob/main/src/components/Taskbar.tsx): launcher UI · Start menu, taskbar, and desktop controls · `src/components/Taskbar.tsx`
- [Window UI](https://github.com/nihalawasthi/zynqos/blob/main/src/components/Window.tsx): window chrome · Movable window container used by desktop apps · `src/components/Window.tsx`
- [File Browser](https://github.com/nihalawasthi/zynqos/blob/main/src/apps/file-browser/ui.tsx): VFS app · Browse and manage files in the browser filesystem · `src/apps/file-browser/ui.tsx`
- [Text Editor](https://github.com/nihalawasthi/zynqos/blob/main/src/apps/text-editor/ui.tsx): VFS app · Edit text files stored in the virtual filesystem · `src/apps/text-editor/ui.tsx`
- [Terminal](https://github.com/nihalawasthi/zynqos/blob/main/src/apps/terminal/ui.tsx): command runner · Runs shell commands, uploads, and Python bridges · `src/apps/terminal/ui.tsx`
- [Python App](https://github.com/nihalawasthi/zynqos/blob/main/src/apps/python/ui.tsx): script runtime UI · User-facing Python execution surface · `src/apps/python/ui.tsx`
- [Settings](https://github.com/nihalawasthi/zynqos/blob/main/src/apps/settings/ui.tsx): preferences app · Configures desktop and account preferences · `src/apps/settings/ui.tsx`
- [Store](https://github.com/nihalawasthi/zynqos/blob/main/src/apps/store/ui.tsx): package store · Discover and install packages for the desktop · `src/apps/store/ui.tsx`
- [ZynqChat](https://github.com/nihalawasthi/zynqos/blob/main/src/apps/zynqchat/ui.tsx): chat app · 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](https://github.com/nihalawasthi/zynqos/blob/main/src/wasm/wasmLoader.ts): execution loader · Loads wasm-bindgen and WASI modules for the desktop · `src/wasm/wasmLoader.ts`
- [Pyodide Loader](https://github.com/nihalawasthi/zynqos/blob/main/src/wasm/pyodideLoader.ts): python runtime · Runs lightweight Python in the browser · `src/wasm/pyodideLoader.ts`
- [Remote Python](https://github.com/nihalawasthi/zynqos/blob/main/src/remotePython/index.ts): python client · Client for the separate Python runtime service · `src/remotePython/index.ts`
- [Terminal WASI](https://github.com/nihalawasthi/zynqos/blob/main/apps/terminal-wasi/src/main.rs): rust binary · Rust WASI command binary used by the terminal · `apps/terminal-wasi/src/main.rs`

### Data Layer

Virtual filesystem, sync, and package management

- [Virtual FS](https://github.com/nihalawasthi/zynqos/blob/main/src/vfs/fs.ts): persistent storage · Browser-persistent filesystem backed by IndexedDB · `src/vfs/fs.ts`
- [VFS Init](https://github.com/nihalawasthi/zynqos/blob/main/src/vfs/init.ts): seeding · Seeds default files and initial filesystem state · `src/vfs/init.ts`
- [Sync Layer](https://github.com/nihalawasthi/zynqos/blob/main/src/storage/sync.ts): storage sync · Coordinates consent and persistence across providers · `src/storage/sync.ts`
- [Auth](https://github.com/nihalawasthi/zynqos/blob/main/src/auth/init.ts): oauth client · OAuth, PKCE, and provider-specific sign-in flows · `src/auth/init.ts`

### Backend Services

Serverless APIs and the Python runtime service

- [Serverless API](https://github.com/nihalawasthi/zynqos/blob/main/api/index.ts): backend functions · OAuth callbacks, sessions, user data, and cron reset · `api/index.ts`
- [Python Runtime](https://github.com/nihalawasthi/zynqos/blob/main/server/py-runtime/app/main.py): container service · Dedicated remote Python execution service · `server/py-runtime/app/main.py`
- [Chat API](https://github.com/nihalawasthi/zynqos/blob/main/src/apps/zynqchat/chatApi.ts): chat backend · Chat database, realtime coordination, and crypto-backed sync · `src/apps/zynqchat/chatApi.ts`

### Distribution

Package registry and import flow

- [Package Manager](https://github.com/nihalawasthi/zynqos/blob/main/src/packages/manager.ts): package system · Validates, stores, and installs desktop packages · `src/packages/manager.ts`
- [MAPP Importer](https://github.com/nihalawasthi/zynqos/blob/main/src/apps/mapp-importer/ui.tsx): import flow · Imports package bundles into the desktop ecosystem · `src/apps/mapp-importer/ui.tsx`

## Connections

- 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
