LanMountainDesktop/docs/EXTERNAL_IPC_ARCHITECTURE.md

External IPC Architecture

Scope

This document defines the current external integration IPC baseline for LanMountainDesktop.

• The delivery focus is external application integration, not plugin process isolation.
• dotnetCampus.Ipc is the single IPC foundation for Host public APIs, Launcher/OOBE startup notifications, and plugin-contributed external services.
• Process isolation remains a future track and stays documented in docs/PLUGIN_PROCESS_ISOLATION_ARCHITECTURE.md.

Design Summary

The public IPC stack is split into two complementary layers:

1. Strongly typed public services
   • Contracts are marked with [IpcPublic].
   • Host exposes service instances through CreateIpcJoint<TContract>(instance).
   • .NET clients connect once and obtain strong typed proxies through CreateIpcProxy<TContract>(peer).
2. Routed notifications
   • JsonIpcDirectRoutedProvider.NotifyAsync is used for one-way event delivery.
   • Startup progress, loading-state updates, catalog changed events, and plugin live events all use routed notify IDs.

This keeps command/query calls explicit and strongly typed while still giving plugins and Launcher a lightweight event channel.

Projects

• LanMountainDesktop.Shared.IPC
  • Public IPC constants, routed notify IDs, DTOs, strong-typed public service contracts, host/client helpers, and DI registration helpers.
• LanMountainDesktop
  • Runs PublicIpcHostService, exposes built-in public services, and folds plugin-contributed services into one external catalog.
• LanMountainDesktop.Launcher
  • Connects to the Host public pipe and listens for startup and loading-state notifications instead of running a custom length-prefixed IPC server.
• LanMountainDesktop.PluginSdk
  • Adds IPluginPublicIpcContributor, IPluginPublicIpcBuilder, and AddPluginPublicIpc(...).

Built-in Public Services

Current built-in [IpcPublic] contracts:

• IPublicAppInfoService
  • Returns application metadata such as version, codename, process id, pipe name, and startup time.
• IPublicShellControlService
  • Allows external .NET clients to query shell status, activate the shell, repair tray readiness, repair taskbar entry visibility, open settings, request restart, and request exit.
• IPublicPluginCatalogService
  • Returns the merged public IPC catalog snapshot exposed by Host.

Routed Notify IDs

Current fixed routed notify IDs:

• lanmountain.catalog.changed
• lanmountain.launcher.startup-progress
• lanmountain.launcher.loading-state

The fixed routed surface is intentionally small. Runtime variation happens in the service catalog and in plugin-contributed service instances, not in ad-hoc top-level route registration after startup.

Host Lifecycle

PublicIpcHostService is started during Host application startup and remains the single external IPC entry point.

Responsibilities:

• Start a named dotnetCampus.Ipc provider.
• Register fixed request routes before StartServer().
• Expose built-in strong-typed public services.
• Maintain the merged service catalog.
• Publish startup and loading-state notifications to connected clients.
• Accept plugin-contributed public services after plugin load.

Launcher / OOBE Migration

Launcher no longer depends on the previous custom named-pipe length-prefixed protocol as the primary path.

• Host publishes StartupProgressMessage through lanmountain.launcher.startup-progress.
• Host publishes LoadingStateMessage through lanmountain.launcher.loading-state.
• Launcher connects as a normal public IPC client and subscribes to those routed notifications.

This means Splash/OOBE is now just another IPC consumer on the same base transport used by external integrators.

Launcher-to-launcher de-duplication is intentionally separate from Host Public IPC. The active Launcher coordinator uses a per-user local pipe and startup-attempt.json heartbeat so secondary Launchers attach to the coordinator before any host process can be started twice.

Plugin Public IPC Contribution Model

Plugins can contribute new external IPC services in two ways:

1. Declarative registration
   • services.AddPluginPublicIpc<TContract, TImplementation>(...)
2. Advanced contributor
   • Register IPluginPublicIpcContributor
   • Use IPluginPublicIpcBuilder to contribute services from plugin DI

At plugin load time the Host runtime:

• discovers PluginPublicIpcServiceRegistration
• executes IPluginPublicIpcContributor
• validates that contributed contracts are [IpcPublic] interfaces
• registers the resolved instances into PublicIpcHostService
• emits lanmountain.catalog.changed

Plugins can also inject IExternalIpcNotificationPublisher and translate internal DI/message-bus events into routed notifications such as:

• lanmountain.plugin.{pluginId}.attendance.updated
• lanmountain.plugin.{pluginId}.status.changed

Service Catalog

The public catalog is represented by PublicIpcCatalogSnapshot and includes:

• built-in and plugin-provided public services
• contract type metadata
• optional object id
• owning pluginId for plugin services
• declared notify IDs
• current loaded/enabled plugin list

This catalog is available through:

• strong-typed public service IPublicPluginCatalogService
• fixed request route lanmountain.catalog.get
• routed notify lanmountain.catalog.changed

Current Limitations

• Strong-typed proxy/joint support is .NET-first.
• Plugin service removal is still restart-bound. New services can be added at runtime, but service removal is not yet modeled as a live unload contract.
• Cross-language clients still need a .NET bridge or sidecar if they want to consume [IpcPublic] contracts directly.
• Plugin process isolation is not part of this delivery. That remains future work.