desktop_engine_architecture

Desktop Engine Architecture & Single-Responsibility Subsystems

Overview

This document outlines the refactored, decoupled engine architecture for YouMeOS Microverse Desktop.

Core Architectural Principles

1. Single Source of Truth: Engine lifecycle, status polling, and log management are unified under BaseEngine and EngineManager.
2. Reusable Utility Layer: Shared streaming, progress calculation, and archive extraction logic are isolated in download.ts.
3. Decoupled Engines:
   • DockerEngine: Exclusively manages Docker Compose lifecycle and service status inspection.
   • EmbeddedEngine: Exclusively manages native FrankenPHP binary execution and HTTP health probing.
4. Typed IPC Bridge: preload/index.ts exposes strongly-typed API wrappers to the renderer without exposing Node.js primitives directly.

Module Breakdown

1. src/main/engine/types.ts

Defines shared interfaces, enums, and callback signatures:

• MicroverseEngine: Core contract for engine implementations.
• EngineStatusInfo: Unified status payload including service statuses and gateway URLs.
• DownloadProgress: Real-time transfer metrics.
• ProgressCallback, LogCallback, StatusCallback.

2. src/main/engine/base.ts

Abstract base class implementing MicroverseEngine:

• Manages log ring buffers (bounded to 600 entries).
• Handles callback subscription and dispatch.
• Provides standard notifyStatus() and pushLog() helpers.

3. src/main/engine/download.ts

Shared networking and archive utility:

• downloadFile(): Resilient HTTP/HTTPS stream downloader with redirect handling and throttled progress reporting.
• downloadAndExtractZip(): Downloads and extracts zip archives into designated directories with automatic cleanup.
• formatBytes(): Standard byte formatting helper.

4. src/main/engine/docker.ts & src/main/engine/docker-setup.ts

• DockerEngine: Extends BaseEngine to execute docker compose commands against the root docker-compose.yml.
• docker-setup.ts: Configures host directory permissions and ensures SQLite database integration drop-ins.

5. src/main/engine/embedded.ts & src/main/engine/embedded-setup.ts

• EmbeddedEngine: Extends BaseEngine to spawn FrankenPHP, detect open ports (80, 8080, 8081), and verify health.
• embedded-setup.ts: Downloads FrankenPHP binary and WordPress core if missing, generates wp-config.php, and configures symlinks.

6. src/main/engine/manager.ts

Coordinates active engine selection and dispatches start/stop/status/log commands to the active engine instance.

7. src/renderer/

• index.html: Clean glassmorphism layout with mechanical tape deck controls, system architecture map, services list, and real-time logs.
• styles.css: Streamlined CSS tokens and glassmorphism styling without dead selectors.
• app.ts: UI presenter with strict event bindings, log formatting, and dynamic status rendering.