Skip to content

Architecture & Platform Policy

Architecture & Platform Policy (Updated)

Status: Active (2025-10-15) Owner: Platform Engineering / Build Governance

Scope

Defines supported CPU architectures, Runtime Identifiers (RIDs), and project organization structure for SmrtHub executables (WinUI / packaged apps, tools, and services). Reinforces deterministic, low-friction development while enabling future expansion.

Current Supported Architecture

  • Primary (development + release): x64 (Platform=x64, RID=win-x64)
  • Deferred (evaluate later): arm64

Rationale

  1. 32-bit (x86) offers no strategic benefit; removing it decreases build matrix complexity, speeds CI, and eliminates configuration mismatch noise.
  2. arm64 adoption is deferred due to uncertain native dependency coverage (Tesseract, PDF/Doc rendering libs) and absence of user demand.
  3. Single-arch focus simplifies solution and project mapping, reducing IDE friction and packaging ambiguity.

Project Configuration Rules

  1. WinUI / packaged projects (e.g., HubWindow) MUST declare only x64 in <Platforms>.
  2. A single <RuntimeIdentifier> (win-x64) is set in the project for deterministic asset resolution.
  3. Solution files map Debug|Any CPU and Release|Any CPU to the project's x64 configuration (no AnyCPU platform defined in the project itself).
  4. Guard target enforces explicit -r win-x64 for Release packaging (MSIX), while Debug auto-defaults.

Project Organization Structure

The SmrtHub codebase is organized into two primary folders under SmrtApps/:

src/ - Shared Libraries & Infrastructure

Contains reusable libraries following Smrt.* naming convention: - Smrt.Config - Configuration path resolution and utilities (namespace: SmrtHub.Config) - Smrt.Logging - Centralized Serilog-based logging (namespace: SmrtHub.Logging) - Smrt.Core - Core shared types and interfaces - Smrt.Infrastructure - Infrastructure utilities - Smrt.Notifications - Notification services - Smrt.UI - WinUI3 shared UI components - Smrt.Security - Windows Credential Manager integration - Smrt.Utils.Clipboard - Clipboard parsing utilities - Provides text/image/HTML extraction and normalizes fragments for downstream components. - OCR hinting: uses a runtime (late-bound) Windows OCR quick-check when available to set textLikely on image fragments, falling back to an edge-based heuristic. No SDK/TFM change is required. Configurable via OcrHintSettings (timeout, max downscale, optional language). Logs via SmrtHub.Logging. - Smrt.Contracts.Triggers - Trigger dispatch contracts - Smrt.Tools.* - CLI tools (TokenGen, CredentialManager)

CSApps/ - Executable Applications

Contains end-user executables and services: - HubWindow - WinUI3 hub/dashboard application - ClipboardMonitor - Clipboard automation service - TriggerManager - Hotkey and trigger coordination - MouseHookPipe - Low-level mouse hook service - SmrtHubSupervisor - Enterprise-grade process supervisor

Architecture Patterns

  1. Library Projects (src/): Compile to .dll, provide reusable functionality, use Smrt.* naming
  2. Application Projects (CSApps/): Compile to .exe, consume libraries from src/, use descriptive names
  3. Dual-Output Pattern (when applicable): Library project compiles all code, thin executable wrapper compiles only entry point
  4. Centralized Build: Directory.Build.props and Directory.Packages.props at solution root manage shared configuration. Developer builds stage all executables into a central Apps tree via Tools/Clean-Build/BuildApps.ps1:
Apps/
└─ <Configuration>/<RuntimeIdentifier>/
    └─ <AppName>/<AppName>.exe

Use Tools/Clean-Build/CleanApps.ps1 -CleanAppsStaging to clean the staging area when needed. The Supervisor and tooling resolve component paths from this staging root using manifest tokens (see ${AppsRoot}).