Skip to content

ARCHITECTURE.md

Latest commit

 

History

History
269 lines (190 loc) · 12.4 KB

ARCHITECTURE.md

File metadata and controls

269 lines (190 loc) · 12.4 KB
Raw

FlashForgeUI-Electron Architecture Overview

Last Updated: 2026-03-11

This document provides a high-level architectural overview of FlashForgeUI-Electron. For detailed information on specific systems, see the specialized reference documents listed at the end.

System Overview

FlashForgeUI-Electron is a sophisticated desktop and headless controller for FlashForge 3D printers built on Electron. The application supports:

  • Multi-Printer Contexts: Simultaneous connections to multiple printers
  • Dual Operating Modes: Desktop GUI and headless server modes
  • Real-Time Monitoring: 3-second polling intervals with instant context switching
  • Advanced Features: Material station support (AD5X), Spoolman filament tracking, RTSP/MJPEG camera streaming
  • Remote Access: Full-featured WebUI with WebSocket real-time updates
  • External Integrations: Discord notifications, desktop notifications, Spoolman integration

Core Architecture Principles

  1. Singleton Managers with Branded Types: Single source of truth for application state
  2. Event-Driven Communication: Loose coupling via EventEmitter pattern
  3. Multi-Context Isolation: Per-printer service instances coordinated by singleton coordinators
  4. Unified GUI/Headless Stack: Same services for both modes, minimal conditional branching
  5. Security First: Context isolation, IPC channel whitelisting, no direct Node.js access in renderers
  6. Type Safety: Strict TypeScript throughout with branded types and comprehensive validation

Bootstrap and Entry Points

Critical Bootstrap Sequence

CRITICAL: src/main/bootstrap.ts MUST be the first import inside src/main/index.ts.

Purpose: Set Electron app name before any singleton captures app.getPath('userData').

// src/main/bootstrap.ts
app.setName('FlashForgeUI');
app.setAppUserModelId('com.ghosttypes.flashforgeui');

Problem Solved: Without bootstrap, singletons like ConfigManager and PrinterDetailsManager lock in the default "Electron" app name, causing GUI/headless configuration desynchronization.

Platform-Specific Paths:

  • macOS: ~/Library/Application Support/FlashForgeUI/
  • Linux: ~/.config/FlashForgeUI/
  • Windows: %APPDATA%/FlashForgeUI/

Entry Points

  • src/main/bootstrap.ts – must be the first import inside src/main/index.ts. It sets the Electron app name/AppUserModelID before singletons (ConfigManager, PrinterDetailsManager, etc.) read app.getPath('userData'), preventing headless/Desktop desync.

  • src/main/index.ts – orchestrates the main process: enforces single-instance locks, parses CLI/headless flags, registers all IPC handlers (src/main/ipc/handlers/index.ts + legacy handlers), instantiates managers/services, and only creates windows after everything else is wired.

  • src/preload/index.ts – exposes the typed window.api bridge with whitelisted channels plus scoped APIs (loading, camera, printerContexts, printerSettings, spoolman, etc.). Every renderer (main window + dialogs) depends on this contract, so keep backward compatibility and cleanup helpers (removeListener, removeAllListeners) intact.

  • src/renderer/src/renderer.ts – initializes the component system, printer tabs, shortcut buttons, layout persistence, and logging hooks before delegating most logic to components/services in the main process.

Manager Layer

Core Managers

  • ConfigManager – centralized config store wrapping AppConfig (src/types/config.ts)
  • PrinterContextManager – issues context IDs, tracks active context, propagates lifecycle events
  • ConnectionFlowManager – discovery flows (GUI + headless), manual IP, auto-connect, saved printer restore
  • PrinterBackendManager – instantiates + maps printer backends (src/printer-backends/*) per context
  • PrinterDetailsManager – persists printer_details.json + per-printer settings inside app.getPath('userData')
  • HeadlessManager – orchestrates --headless boot, WebUI startup, polling, and graceful shutdown
  • LoadingManager – modal loading overlays surfaced via IPC (main window + dialogs)
  • WindowManager / WindowFactory – renderer/window lifecycle coordination (main window + dialogs)
  • CalibrationManager – printer calibration data management and workflow coordination

Service Layer

Polling & Monitoring

  • PrinterPollingService, MainProcessPollingCoordinator (single-printer), MultiContextPollingCoordinator
  • PrintStateMonitor, MultiContextPrintStateMonitor
  • TemperatureMonitoringService, MultiContextTemperatureMonitor

Connection/Discovery

  • PrinterDiscoveryService, ConnectionEstablishmentService, ConnectionStateManager
  • AutoConnectService, SavedPrinterService, DialogIntegrationService

Camera & Streaming

  • Go2rtcService - unified camera streaming using go2rtc (WebRTC/MSE/MJPEG)
  • Go2rtcBinaryManager - go2rtc binary lifecycle management (ports hardcoded: 1984 API, 8555 WebRTC)
  • CameraStreamCoordinator - shared camera stream reconciliation helpers

Notifications

  • PrinterNotificationCoordinator, MultiContextNotificationCoordinator
  • services/notifications/*, services/discord/DiscordNotificationService.ts

Filament

  • SpoolmanService, SpoolmanIntegrationService, SpoolmanUsageTracker
  • MultiContextSpoolmanTracker, SpoolmanHealthMonitor

Misc/System

  • PrinterDataTransformer, PrintStateMonitor, EnvironmentDetectionService
  • AutoUpdateService, LogService, StaticFileManager
  • ThumbnailCacheService - Persistent file-based cache for printer job thumbnails
  • ThumbnailRequestQueue - Backend-aware thumbnail request queue
  • DebugLogService - Debug logging service
  • ContextServiceInitializer - Per-context service initialization coordinator

Printer Backend System

Backend Hierarchy

BasePrinterBackend (abstract)
├── GenericLegacyBackend
│   └── Uses: FlashForgeClient only
│   └── Features: Basic legacy support
│
└── DualAPIBackend (abstract)
    ├── Adventurer5MBackend
    │   └── Uses: FiveMClient + FlashForgeClient
    │   └── Features: Auto-enabled LED (TCP)
    │
    ├── Adventurer5MProBackend
    │   └── Uses: FiveMClient + FlashForgeClient
    │   └── Features: Built-in RTSP, LED (HTTP), filtration
    │
    └── AD5XBackend
        └── Uses: FiveMClient + FlashForgeClient
        └── Features: 4-slot material station

Backend Selection Logic

Backend selection uses detectPrinterModelType() from src/main/utils/PrinterUtils.ts with includes() on lowercase model strings:

Adventurer5MProBackend → typeNameLower.includes('5m pro')
Adventurer5MBackend    → typeNameLower.includes('5m')
AD5XBackend           → typeNameLower.includes('ad5x')
GenericLegacyBackend  → All others (fallback)

Key Architectural Patterns

Multi-Context Coordinator Pattern

MultiContextPollingCoordinator (singleton)
├── PrinterPollingService (context-1)
├── PrinterPollingService (context-2)
└── PrinterPollingService (context-3)

See MULTI_CONTEXT.md for details.

Event-Driven Communication

All major systems use EventEmitter for loose coupling:

  • Managers emit lifecycle events
  • Services listen and react
  • No circular dependencies
  • Clean separation of concerns

IPC Security Model

Renderer Process (Sandboxed)
    ↓ window.api calls
Preload Script (Privileged)
    ↓ Channel validation
    ↓ contextBridge
ipcRenderer
    ↓ Whitelisted channels
ipcMain Handlers
    ↓ Business logic
Services/Managers

See IPC_COMMUNICATION.md for details.

File Organization

Bootstrapping & Entry

  • src/main/bootstrap.ts – sets app name/userData path before anything else loads
  • src/main/index.ts – main-process orchestrator (imports bootstrap first, registers IPC, creates windows)
  • src/preload/index.ts / src/renderer/src/ui/component-dialog/component-dialog-preload.ts – context bridges for main + dialog renderers

Managers & Multi-Context Core

  • src/main/managers/PrinterContextManager.ts, PrinterBackendManager.ts, ConnectionFlowManager.ts, PrinterDetailsManager.ts, HeadlessManager.ts, LoadingManager.ts
  • src/main/services/MultiContextPollingCoordinator.ts, MultiContextPrintStateMonitor.ts, MultiContextTemperatureMonitor.ts, MultiContextSpoolmanTracker.ts, MultiContextNotificationCoordinator.ts
  • src/main/services/MainProcessPollingCoordinator.ts, PrinterPollingService.ts for legacy single-printer paths

Backends & Printers

  • src/main/printer-backends/*.ts – Legacy, Adventurer5M, Adventurer5M Pro, AD5X implementations
  • src/main/printer-backends/ad5x/* – material station transforms/types/utils

Renderer & Components

  • src/renderer/src/renderer.ts, src/renderer/src/gridController.ts, src/renderer/src/shortcutButtons.ts, src/renderer/src/perPrinterStorage.ts, src/renderer/src/logging.ts
  • src/renderer/src/ui/components/** (ComponentManager, printer tabs, job info, etc.) + src/renderer/src/ui/gridstack/** for layout/palette logic
  • src/renderer/src/ui/component-dialog/** – component dialog renderer + preload mirrors

IPC & Windows

  • src/main/ipc/handlers/index.ts + domain handlers in src/main/ipc/handlers/*.ts, camera-ipc-handler.ts, printer-context-handlers.ts, WindowControlHandlers.ts, DialogHandlers.ts
  • src/main/windows/WindowManager.ts, src/main/windows/WindowFactory.ts, src/main/windows/factories/*, src/main/windows/dialogs/*

Settings Dialog

  • src/renderer/src/ui/settings/settings-renderer.ts – main orchestrator for dual settings management (global + per-printer)
  • src/renderer/src/ui/settings/sections/SettingsSection.ts – base interface for modular sections
  • src/renderer/src/ui/settings/sections/*.ts – individual setting sections (AutoUpdate, DesktopTheme, Discord, InputDependency, PrinterContext, RoundedUI, SpoolmanTest, Tab)
  • src/renderer/src/ui/settings/types.ts, src/renderer/src/ui/settings/types/external.ts – shared type definitions

Utilities & Types

  • src/main/utils/camera-utils.ts – camera URL building, stream resolution helpers
  • src/main/utils/SecureStorage.ts – secure credential storage
  • src/main/utils/PrinterUtils.ts – detectPrinterModelType(), detectPrinterFamily(), backend selection helpers
  • src/main/utils/validation.utils.ts – input validation helpers
  • src/main/utils/HeadlessArguments.ts, HeadlessDetection.ts, HeadlessLogger.ts, RoundedUICompatibility.ts, CSSVariables.ts, error.utils.ts, extraction.utils.ts, EventEmitter.ts
  • src/shared/utils/time.utils.ts – time formatting and duration utilities
  • src/main/types/go2rtc.types.ts – go2rtc service type definitions
  • src/shared/types/ – contexts, polling, config, printers, spoolman, discord, camera, printer backend operations, IPC

WebUI Routes

  • src/main/webui/server/routes/camera-routes.ts – camera streaming endpoints
  • src/main/webui/server/routes/calibration-routes.ts – printer calibration data endpoints
  • src/main/webui/server/routes/debug-routes.ts – debug and diagnostics endpoints
  • src/main/webui/server/routes/theme-routes.ts – theme management endpoints
  • src/main/webui/server/routes/filtration-routes.ts – filtration system control endpoints
  • src/main/webui/server/routes/printer-control-routes.ts – printer control commands
  • src/main/webui/server/routes/context-routes.ts, job-routes.ts, printer-status-routes.ts, spoolman-routes.ts, temperature-routes.ts, route-helpers.ts

Reference Documentation

For detailed information on specific systems, see: