# xgeniaorg/xgenia architecture

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

- Interactive diagram: https://gitdiagram.com/xgeniaorg/xgenia
- Repository: https://github.com/xgeniaorg/xgenia

## Overview

1. **Monorepo shape**
   - This is a multi-package workspace built around a low-code platform. The main product is the **XGENIA Editor**, but the repo also contains the **runtime**, **viewer libraries**, **platform abstractions**, **Git integration**, **AI/MCP tooling**, and **cloud/runtime helpers**.
   - The code is organized so the editor, runtime, and viewer can evolve separately but still share types and platform contracts.

2. **Primary product boundary: the Electron editor**
   - `packages/xgenia-editor` is the desktop application, implemented as an **Electron** app with a **main process** and a large **renderer/UI layer**.
   - The renderer contains the visual authoring experience: node graph editor, property panel, sidebars, dialogs, project settings, version control panel, cloud service panels, asset explorer, and AI/chat panels.
   - The Electron main process hosts local services such as OAuth callbacks, web servers, cloud-function servers, design-tool import support, auto-updater logic, and file/storage helpers.

3. **Visual programming model**
   - The editor is centered on a **node graph / component model**. Projects are composed of nodes, ports, connections, pages, styles, variants, and assets.
   - The editor’s “model” layer in `src/editor/src/models` and `src/editor/src/views/nodegrapheditor*` coordinates graph state, node type adapters, undo history, warnings, tutorials, comments, and project patching/merging.
   - This is the key domain boundary: UI panels mutate project state, while compilation/export translates that state into runnable artifacts.

4. **Runtime and viewer split**
   - `packages/xgenia-runtime` is the execution engine for generated projects. It contains the node implementations, graph/runtime models, event handling, node registry, services, and converters for different node families.
   - `packages/xgenia-viewer-react` is the React-based viewer/runtime used to render and execute apps in browser-like environments. It provides visual components, node implementations, navigation logic, and deployment/viewer bundles.
   - The runtime/viewer boundary is important: the editor produces a project model, and the runtime/viewer consume it to render or execute the application.

5. **Compilation, export, and deployment pipeline**
   - The editor contains compilation/export utilities under `src/editor/src/utils/compilation` and `src/editor/src/utils/exporter`.
   - These modules transform the project graph into deployable output, including HTML processing, bundling, asset copying, sitemap generation, and deployment-specific passes.
   - Deployment targets include local folders, cloud services, and specialized paths for cloud functions / Supabase edge functions, indicating the platform supports both static and server-backed outputs.

6. **Cloud and backend integrations**
   - `packages/xgenia-viewer-cloud` packages the viewer for cloud execution and exposes file/user APIs plus sandboxed runtime entrypoints.
   - The editor also has explicit cloud-service panels and models for services, Git stats, external cloud services, and Supabase initialization.
   - There is a `packages/xgenia-parse-dashboard` package as a bundled Parse Dashboard integration, which suggests support for a Parse-style backend/admin workflow in addition to newer cloud options.

7. **Git and version-control subsystem**
   - `packages/xgenia-git` is a substantial Git wrapper that implements core Git operations, history, branching, status/diff parsing, fetch/pull/push, stash, merge, clone, and authentication handling.
   - The editor’s version-control panel uses this package to show branches, local changes, diffs, stash/merge state, and remote configuration.
   - This is a distinct subsystem rather than a thin wrapper: it provides the repository-level state machine behind the UI.

8. **Platform abstraction layer**
   - `packages/xgenia-platform` plus `packages/xgenia-platform-node` and `packages/xgenia-platform-electron` define shared abstractions for filesystem, storage, and runtime platform behavior across browser, Node, and Electron environments.
   - This layer is what lets the editor/runtime run in multiple environments without hard-coding the storage backend or filesystem implementation.
   - In the architecture diagram, this sits between app logic and the actual OS/browser capabilities.

9. **AI and MCP integration**
   - The editor includes an AI/chat experience, MCP server browsing, and a plugin bridge for chat tools.
   - `packages/xgenia-mcp`, `packages/xgenia-mcp-server`, and `packages/xgenia-external-external-mcps` provide the tool/server side of that integration, including external provider adapters such as HuggingFace and Vertex.
   - The bridge between the editor and these tool servers is a major boundary: the editor initiates actions, but tool execution happens in separate MCP-capable services or sandboxes.

10. **Shared assets, UI components, and design system**
   - `packages/xgenia-core-ui` is a reusable component library used by the editor and preview surfaces. It contains many generic UI primitives and domain-specific components for AI, app shell, property panels, tree views, popups, typography, and layout.
   - This package also includes Storybook and design-token/story content, so it functions as the platform’s design system and component showcase.
   - Fonts, icons, global styles, and utility functions are centralized here to keep the editor and preview surfaces visually consistent.

11. **Preview, templates, and document views**
   - The editor contains multiple preview/template layers: launcher previews, property-panel previews, document views, and runtime templates.
   - These are used to render projects, onboarding/launcher experiences, and specialized editor documents such as component diffs and project settings.
   - In the diagram, these are consumer-facing rendering layers built on top of the shared core UI and runtime contracts.

12. **Local tooling and automation**
   - The repo is managed as a workspace using `lerna`, `nx`, and multiple TypeScript/webpack configurations.
   - GitHub Actions workflows handle editor/runtime builds, tests, releases, notifications, and cloud-runtime publishing.
   - The top-level `scripts/` directory orchestrates building, launching, packaging, test startup, private submodule setup, and platform-specific build steps.

13. **Typical end-to-end data flow**
   - A user edits a project in the Electron renderer; the editor updates the project model, node graph, styles, assets, and settings.
   - The project can then be compiled/exported through editor utilities into runtime-compatible artifacts.
   - Those artifacts are consumed by the React viewer / runtime packages for preview, by deployment targets for production, or by Git/cloud subsystems for versioned collaboration and publishing.

Main entry points: [`packages/xgenia-editor/src/editor/src`](https://github.com/xgeniaorg/xgenia/tree/main/packages/xgenia-editor/src/editor/src) (Editor UI), [`packages/xgenia-editor/src/main`](https://github.com/xgeniaorg/xgenia/tree/main/packages/xgenia-editor/src/main) (Main Process), [`packages/xgenia-editor/src/editor/src/views/panels`](https://github.com/xgeniaorg/xgenia/tree/main/packages/xgenia-editor/src/editor/src/views/panels) (Side Panels), [`packages/xgenia-mcp/src`](https://github.com/xgeniaorg/xgenia/tree/main/packages/xgenia-mcp/src) (MCP Service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_workspace["Workspace"]
  node_scripts["Scripts<br/>build/launch automation"]
  node_core_ui["Core UI<br/>shared design system"]
end

subgraph group_editor["XGENIA Editor"]
  node_editor_main["Main Process<br/>electron main"]
  node_editor_renderer["Editor UI<br/>renderer app"]
  node_editor_model{{"Project Model"}}
  node_editor_graph["Graph Editor<br/>graph authoring"]
  node_editor_panels["Side Panels<br/>authoring panels"]
  node_editor_export{{"Compile & Export<br/>build pipeline"}}
  node_editor_deploy["Exporter<br/>packaging/deploy"]
end

subgraph group_runtime["Runtime & Viewer"]
  node_runtime_core["Runtime Core<br/>execution engine"]
  node_runtime_api["Runtime APIs<br/>node converters"]
  node_viewer_react["Viewer React<br/>browser viewer"]
  node_viewer_cloud["Cloud Viewer<br/>cloud runtime"]
end

subgraph group_platform["Platform Abstractions"]
  node_platform_web["Platform Core<br/>shared platform"]
  node_platform_node["Node Platform<br/>node adapter"]
  node_platform_electron["Electron Platform<br/>electron adapter"]
end

subgraph group_integrations["Integrations"]
  node_git_pkg{{"Git Engine<br/>git wrapper"}}
  node_mcp_pkg["MCP Service<br/>tool service"]
  node_mcp_server["MCP Server<br/>tool server"]
  node_external_mcps["External MCPs<br/>provider adapters"]
  node_parse_dashboard["Parse Dashboard<br/>backend admin"]
end

node_scripts -->|"build/start"| node_editor_main
node_scripts -->|"build viewer"| node_viewer_react
node_editor_main -->|"filesystem"| node_platform_electron
node_editor_main -->|"version control"| node_git_pkg
node_editor_main -->|"ai tools"| node_mcp_pkg
node_editor_renderer -->|"state"| node_editor_model
node_editor_renderer -->|"authoring"| node_editor_graph
node_editor_renderer -->|"panels"| node_editor_panels
node_editor_renderer -->|"ui"| node_core_ui
node_editor_graph -->|"patches"| node_editor_model
node_editor_panels -->|"git ui"| node_git_pkg
node_editor_panels -->|"mcp ui"| node_mcp_pkg
node_editor_panels -->|"cloud"| node_viewer_cloud
node_editor_export -->|"compile"| node_editor_model
node_editor_export -->|"targets"| node_viewer_react
node_editor_export -->|"deploy"| node_viewer_cloud
node_editor_deploy -->|"bundle"| node_viewer_react
node_runtime_core -->|"adapters"| node_runtime_api
node_viewer_react -->|"executes"| node_runtime_core
node_viewer_cloud -->|"sandbox"| node_runtime_core
node_platform_web -->|"node impl"| node_platform_node
node_platform_web -->|"electron impl"| node_platform_electron
node_git_pkg -->|"host fs"| node_platform_node
node_mcp_pkg -->|"serve"| node_mcp_server
node_mcp_pkg -->|"providers"| node_external_mcps
node_parse_dashboard -.->|"legacy backend"| node_viewer_cloud

click node_scripts "https://github.com/xgeniaorg/xgenia/tree/main/scripts"
click node_core_ui "https://github.com/xgeniaorg/xgenia/tree/main/packages/xgenia-core-ui"
click node_editor_main "https://github.com/xgeniaorg/xgenia/tree/main/packages/xgenia-editor/src/main"
click node_editor_renderer "https://github.com/xgeniaorg/xgenia/tree/main/packages/xgenia-editor/src/editor/src"
click node_editor_model "https://github.com/xgeniaorg/xgenia/tree/main/packages/xgenia-editor/src/editor/src/models"
click node_editor_graph "https://github.com/xgeniaorg/xgenia/tree/main/packages/xgenia-editor/src/editor/src/views/nodegrapheditor"
click node_editor_panels "https://github.com/xgeniaorg/xgenia/tree/main/packages/xgenia-editor/src/editor/src/views/panels"
click node_editor_export "https://github.com/xgeniaorg/xgenia/tree/main/packages/xgenia-editor/src/editor/src/utils/compilation"
click node_editor_deploy "https://github.com/xgeniaorg/xgenia/tree/main/packages/xgenia-editor/src/editor/src/utils/exporter"
click node_runtime_core "https://github.com/xgeniaorg/xgenia/tree/main/packages/xgenia-runtime/src"
click node_runtime_api "https://github.com/xgeniaorg/xgenia/tree/main/packages/xgenia-runtime/src/api"
click node_viewer_react "https://github.com/xgeniaorg/xgenia/tree/main/packages/xgenia-viewer-react/src"
click node_viewer_cloud "https://github.com/xgeniaorg/xgenia/tree/main/packages/xgenia-viewer-cloud/src"
click node_platform_web "https://github.com/xgeniaorg/xgenia/tree/main/packages/xgenia-platform/src"
click node_platform_node "https://github.com/xgeniaorg/xgenia/tree/main/packages/xgenia-platform-node/src"
click node_platform_electron "https://github.com/xgeniaorg/xgenia/tree/main/packages/xgenia-platform-electron/src"
click node_git_pkg "https://github.com/xgeniaorg/xgenia/tree/main/packages/xgenia-git/src"
click node_mcp_pkg "https://github.com/xgeniaorg/xgenia/tree/main/packages/xgenia-mcp/src"
click node_mcp_server "https://github.com/xgeniaorg/xgenia/tree/main/packages/xgenia-mcp-server/src"
click node_external_mcps "https://github.com/xgeniaorg/xgenia/tree/main/packages/xgenia-external-external-mcps"
click node_parse_dashboard "https://github.com/xgeniaorg/xgenia/tree/main/packages/xgenia-parse-dashboard/Parse-Dashboard"

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_scripts,node_core_ui toneBlue
class node_editor_main,node_editor_renderer,node_editor_model,node_editor_graph,node_editor_panels,node_editor_export,node_editor_deploy toneAmber
class node_runtime_core,node_runtime_api,node_viewer_react,node_viewer_cloud toneMint
class node_platform_web,node_platform_node,node_platform_electron toneRose
class node_git_pkg,node_mcp_pkg,node_mcp_server,node_external_mcps,node_parse_dashboard toneIndigo
```

## Components

### Workspace

Monorepo orchestration and shared tooling

- [Scripts](https://github.com/xgeniaorg/xgenia/tree/main/scripts): build/launch automation · Top-level scripts for building, starting, testing, and packaging the workspace · `scripts`
- [Core UI](https://github.com/xgeniaorg/xgenia/tree/main/packages/xgenia-core-ui): shared design system · Reusable UI primitives, panels, previews, and Storybook-driven components · `packages/xgenia-core-ui`

### XGENIA Editor

Electron desktop app and authoring surface

- [Main Process](https://github.com/xgeniaorg/xgenia/tree/main/packages/xgenia-editor/src/main): electron main · Electron main entry and local host services · `packages/xgenia-editor/src/main`
- [Editor UI](https://github.com/xgeniaorg/xgenia/tree/main/packages/xgenia-editor/src/editor/src): renderer app · Electron renderer containing pages, views, panels, and document shells · `packages/xgenia-editor/src/editor/src`
- [Project Model](https://github.com/xgeniaorg/xgenia/tree/main/packages/xgenia-editor/src/editor/src/models): graph/project model · Project state, node graph model, patches, styles, variants, and undo/warnings · `packages/xgenia-editor/src/editor/src/models`
- [Graph Editor](https://github.com/xgeniaorg/xgenia/tree/main/packages/xgenia-editor/src/editor/src/views/nodegrapheditor): graph authoring · Node graph editor views, canvas, node picker, and property editing flows · `packages/xgenia-editor/src/editor/src/views/nodegrapheditor`
- [Side Panels](https://github.com/xgeniaorg/xgenia/tree/main/packages/xgenia-editor/src/editor/src/views/panels): authoring panels · Property, assets, cloud, project settings, version control, AI, and explorer panels · `packages/xgenia-editor/src/editor/src/views/panels`
- [Compile & Export](https://github.com/xgeniaorg/xgenia/tree/main/packages/xgenia-editor/src/editor/src/utils/compilation): build pipeline · Transforms project state into deployable runtime artifacts · `packages/xgenia-editor/src/editor/src/utils/compilation`
- [Exporter](https://github.com/xgeniaorg/xgenia/tree/main/packages/xgenia-editor/src/editor/src/utils/exporter): packaging/deploy · Bundling, hashing, JSON export, router output, and deployment helpers · `packages/xgenia-editor/src/editor/src/utils/exporter`

### Runtime & Viewer

Execution and rendering packages for generated apps

- [Runtime Core](https://github.com/xgeniaorg/xgenia/tree/main/packages/xgenia-runtime/src): execution engine · Graph runtime, node registry, models, events, and node implementations · `packages/xgenia-runtime/src`
- [Runtime APIs](https://github.com/xgeniaorg/xgenia/tree/main/packages/xgenia-runtime/src/api): node converters · Converters and API bridges for collections, math, signals, Supabase, and cloud nodes · `packages/xgenia-runtime/src/api`
- [Viewer React](https://github.com/xgeniaorg/xgenia/tree/main/packages/xgenia-viewer-react/src): browser viewer · React-based viewer/runtime for rendering and executing apps · `packages/xgenia-viewer-react/src`
- [Cloud Viewer](https://github.com/xgeniaorg/xgenia/tree/main/packages/xgenia-viewer-cloud/src): cloud runtime · Viewer packaging, sandbox entrypoints, and user/file APIs for cloud execution · `packages/xgenia-viewer-cloud/src`

### Platform Abstractions

Shared filesystem and storage interfaces across runtimes

- [Platform Core](https://github.com/xgeniaorg/xgenia/tree/main/packages/xgenia-platform/src): shared platform · Environment-agnostic filesystem, storage, platform, and utility contracts · `packages/xgenia-platform/src`
- [Node Platform](https://github.com/xgeniaorg/xgenia/tree/main/packages/xgenia-platform-node/src): node adapter · Node filesystem and storage implementation · `packages/xgenia-platform-node/src`
- [Electron Platform](https://github.com/xgeniaorg/xgenia/tree/main/packages/xgenia-platform-electron/src): electron adapter · Electron filesystem and platform implementation · `packages/xgenia-platform-electron/src`

### Integrations

Git, AI/MCP, cloud, and backend connectors

- [Git Engine](https://github.com/xgeniaorg/xgenia/tree/main/packages/xgenia-git/src): git wrapper · Core Git operations, history, branching, remotes, diff, stash, merge, and auth · `packages/xgenia-git/src`
- [MCP Service](https://github.com/xgeniaorg/xgenia/tree/main/packages/xgenia-mcp/src): tool service · MCP client/service helpers and configuration utilities · `packages/xgenia-mcp/src`
- [MCP Server](https://github.com/xgeniaorg/xgenia/tree/main/packages/xgenia-mcp-server/src): tool server · Standalone MCP server entrypoint and test harness · `packages/xgenia-mcp-server/src`
- [External MCPs](https://github.com/xgeniaorg/xgenia/tree/main/packages/xgenia-external-external-mcps): provider adapters · Provider-specific MCP implementations for HuggingFace and Vertex · `packages/xgenia-external-external-mcps`
- [Parse Dashboard](https://github.com/xgeniaorg/xgenia/tree/main/packages/xgenia-parse-dashboard/Parse-Dashboard): backend admin · Bundled Parse Dashboard integration for legacy/backend workflows · `packages/xgenia-parse-dashboard/Parse-Dashboard`

## Connections

- Scripts → Main Process: build/start · Launches and packages the editor application
- Scripts → Viewer React: build viewer · Builds runtime/viewer bundles
- Main Process → Electron Platform: filesystem · Uses Electron-specific platform services
- Main Process → Git Engine: version control · Delegates repository operations to the Git subsystem
- Main Process → MCP Service: ai tools · Connects editor-side AI tooling to MCP services
- Editor UI → Project Model: state · Reads and mutates project graph state
- Editor UI → Graph Editor: authoring · Hosts the visual graph editor experience
- Editor UI → Side Panels: panels · Composes the side panels and document workflows
- Editor UI → Core UI: ui · Uses shared design-system components
- Graph Editor → Project Model: patches · Applies graph edits, history, and node adapter changes
- Side Panels → Git Engine: git ui · Drives branch, diff, stash, and merge views
- Side Panels → MCP Service: mcp ui · Presents MCP server browsing and chat tooling
- Side Panels → Cloud Viewer: cloud · Surfaces cloud/runtime services and deployment integration
- Compile & Export → Project Model: compile · Compiles project state into runtime-ready artifacts
- Compile & Export → Viewer React: targets · Produces bundles consumed by the React viewer
- Compile & Export → Cloud Viewer: deploy · Emits cloud-friendly outputs and sandboxes
- Exporter → Viewer React: bundle · Packages viewer assets and deployment payloads
- Runtime Core → Runtime APIs: adapters · Uses API converters for node families and integrations
- Viewer React → Runtime Core: executes · Consumes runtime contracts to render and run apps
- Cloud Viewer → Runtime Core: sandbox · Runs runtime logic in cloud execution contexts
- Platform Core → Node Platform: node impl · Provides the shared contracts implemented by Node
- Platform Core → Electron Platform: electron impl · Provides the shared contracts implemented by Electron
- Git Engine → Node Platform: host fs · Relies on Node-side filesystem and process capabilities
- MCP Service → MCP Server: serve · Shared MCP service logic underpins the server entrypoint
- MCP Service → External MCPs: providers · Connects to external provider-specific MCP implementations
- Parse Dashboard → Cloud Viewer: legacy backend · Supports Parse-style backend/admin workflows alongside cloud runtime
