How xgeniaorg/xgenia works
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: editor/src Editor UI · main Main Process · panels Side Panels · xgenia-mcp/src MCP Service
Components 21
Workspace
Monorepo orchestration and shared tooling
XGENIA Editor
Electron desktop app and authoring surface
- Main Process · Electron main entry and local host services
packages/xgenia-editor/src/main - Editor UI · Electron renderer containing pages, views, panels, and document shells
packages/xgenia-editor/src/editor/src - Project Model · Project state, node graph model, patches, styles, variants, and undo/warnings
packages/xgenia-editor/src/editor/src/models - Graph Editor · Node graph editor views, canvas, node picker, and property editing flows
packages/xgenia-editor/src/editor/src/views/nodegrapheditor - Side Panels · Property, assets, cloud, project settings, version control, AI, and explorer panels
packages/xgenia-editor/src/editor/src/views/panels - Compile & Export · Transforms project state into deployable runtime artifacts
packages/xgenia-editor/src/editor/src/utils/compilation - Exporter · 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 · Graph runtime, node registry, models, events, and node implementations
packages/xgenia-runtime/src - Runtime APIs · Converters and API bridges for collections, math, signals, Supabase, and cloud nodes
packages/xgenia-runtime/src/api - Viewer React · React-based viewer/runtime for rendering and executing apps
packages/xgenia-viewer-react/src - Cloud Viewer · 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 · Environment-agnostic filesystem, storage, platform, and utility contracts
packages/xgenia-platform/src - Node Platform · Node filesystem and storage implementation
packages/xgenia-platform-node/src - Electron Platform · Electron filesystem and platform implementation
packages/xgenia-platform-electron/src
Integrations
Git, AI/MCP, cloud, and backend connectors
- Git Engine · Core Git operations, history, branching, remotes, diff, stash, merge, and auth
packages/xgenia-git/src - MCP Service · MCP client/service helpers and configuration utilities
packages/xgenia-mcp/src - MCP Server · Standalone MCP server entrypoint and test harness
packages/xgenia-mcp-server/src - External MCPs · Provider-specific MCP implementations for HuggingFace and Vertex
packages/xgenia-external-external-mcps - Parse Dashboard · Bundled Parse Dashboard integration for legacy/backend workflows
packages/xgenia-parse-dashboard/Parse-Dashboard
Connections 26
- 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