Skip to content

SmrtHub Specification

This is the complete technical specification for the SmrtHub hybrid C#/.NET + Python integrated desktop automation suite.

Document Status

This specification is actively maintained and reflects the current implementation. Last updated: July 2025.

Executive Summary

SmrtHub is a comprehensive desktop automation platform that intelligently monitors, processes, and routes digital content across applications and workflows. It combines the reliability of C# desktop applications with the flexibility of Python processing engines to create a seamless automation experience.

Core Architecture

Hybrid Design Philosophy

SmrtHub employs a hybrid architecture that leverages the strengths of both C# and Python:

  • C# Desktop Applications - System integration, Windows services, and native UI components
  • Python Core Engine - Content processing, AI detection, and business logic
  • HTTP Communication Bridge - Seamless real-time integration between technologies

System Components

graph TB
    subgraph "C# Desktop Layer"
        WD[SmrtHub.App<br/>Process Manager]
        CM[ClipboardMonitor<br/>System Integration]
        SO[SmrtHub<br/>UI Indicators]
        TM[TriggerManager<br/>Automation Engine]
    end

    subgraph "Communication Bridge"
        HTTP[HTTP Bridge Server<br/>Port 5001]
        WS[WebSocket Support<br/>Real-time Events]
    end

    subgraph "Python Core Engine"
        RT[Runtime Management]
        SD[Smrt Detection]
        SM[SmrtSpace Management]
        FE[Flow Enhancement]
        UT[Utilities & Logging]
    end

    WD --> HTTP
    CM --> HTTP
    SO --> HTTP
    TM --> HTTP

    HTTP --> RT
    HTTP --> SD
    HTTP --> SM
    HTTP --> FE
    HTTP --> UT

Technical Specifications

Development Environment

Component Specification
Target Framework .NET 8.0-windows
Python Version 3.12+
IDE Support Visual Studio 2022, VS Code
Build System MSBuild + PowerShell automation
Documentation MkDocs + mkdocstrings

Project Structure

SmrtApps/
├── CSApps/                    # C# .NET Applications
│   ├── SmrtHub.App/             # Central orchestrator and process manager
│   ├── ClipboardMonitor/     # Real-time clipboard monitoring
│   ├── SmrtApps/        # Visual status smrthub system
│   ├── TriggerManager/       # Event-driven automation engine
│   ├── SyncManager/         # Multi-device synchronization (future)
│   └── AppDialogs/          # Configuration UI dialogs
├── PythonApp/               # Python Core Engine
│   ├── python_core/         # Main Python package
│   │   ├── config/          # Configuration management
│   │   ├── smrtdetect/     # Content detection and analysis
│   │   ├── runtime/         # Core runtime and state management
│   │   ├── net/            # Network bridge and routing
│   │   ├── smrtspace_mgt/ # Workspace management
│   │   ├── flow_enhance/   # Workflow enhancement
│   │   ├── ui/             # User interface components
│   │   └── utils/          # Utilities and helpers
│   ├── venv/               # Python virtual environment
│   └── requirements.txt    # Python dependencies
├── SmrtBrowsers/          # Browser extension support
├── tools/                  # Build and development scripts
├── docs/                   # MkDocs documentation
└── Assets/                 # Shared application resources

Component Specifications

C# Applications

SmrtHub.App - Central Orchestrator

  • Purpose: Process lifecycle management and system coordination
  • Technology: .NET 8.0 Windows Service
  • Responsibilities:
  • Launch and monitor all SmrtHub components
  • System tray integration and status management
  • Health monitoring via heartbeat system
  • Inter-process communication coordination
  • Graceful shutdown and restart handling

ClipboardMonitor - System Integration

  • Purpose: Real-time clipboard monitoring and event detection
  • Technology: .NET 8.0 Desktop Application with Win32 API
  • Responsibilities:
  • Monitor clipboard content changes
  • Detect content types and sources
  • Route clipboard events to Python core
  • Handle clipboard history and management
  • Integration with Windows clipboard ecosystem

SmrtHub - Visual Feedback

  • Purpose: Visual status indicators and user feedback
  • Technology: .NET 8.0 WPF Application with smrthub rendering
  • Responsibilities:
  • Display real-time status indicators
  • Provide visual feedback for automation events
  • Show progress indicators for long operations
  • Render contextual UI smrthubs
  • Integration with desktop window management

TriggerManager - Automation Engine

  • Purpose: Event-driven automation and workflow management
  • Technology: .NET 8.0 Service with rule engine
  • Responsibilities:
  • Process automation triggers and rules
  • Execute workflow actions and sequences
  • Manage automation state and context
  • Integration with system events and timers
  • User-defined automation script execution

Python Core Engine

The Python core handles all content processing, smrt detection, and business logic:

Configuration Management (config/)

  • Modules: smrtdetect_indexer_settings, smrtspace_config, user_flags, localsource_exclusions
  • Purpose: Centralized configuration management and user preferences
  • Features:
  • JSON-based configuration with validation
  • Runtime configuration updates
  • User preference persistence
  • SmrtSpace workspace configuration
  • Exclusion rules and filters

Smrt Detection Engine (smrtdetect/)

  • Modules: adobe_parser, file_indexer, filename, localsource, magika_detector, recent_folder_tracker, websource
  • Purpose: Intelligent content analysis and file type detection
  • Features:
  • AI-powered file type detection using Google's Magika
  • Adobe document parsing and metadata extraction
  • Web content analysis and source detection
  • Local file system indexing and tracking
  • Recent folder and pattern analysis
  • Smrt filename generation and routing

Runtime Management (runtime/)

  • Modules: file_saver, router, save_trigger, save_worker, shared_state
  • Purpose: Core application runtime and state management
  • Features:
  • Background save queue processing
  • Content routing and organization
  • Append mode for continuous content capture
  • Thread-safe shared state management
  • Event-driven save triggers
  • File format detection and conversion
  • Note: Image text-likelihood hinting (textLikely) is handled in C# Clipboard utilities to keep processing unified in the current pipeline.

Network Bridge (net/)

  • Modules: bridge_server, web_listener, wsgi, routes/
  • Purpose: HTTP/WebSocket communication layer for C#/Python integration
  • Features:
  • Flask-based HTTP API server (port 5001)
  • WebSocket support for real-time events
  • RESTful API endpoints for C# components
  • Request routing and middleware
  • Authentication and security
  • CORS support for browser extensions

SmrtSpace Management (smrtspace_mgt/)

  • Modules: config_bridge, smrtspace
  • Purpose: Workspace-aware file organization and management
  • Features:
  • Context-aware directory structures
  • Project-based file organization
  • Smrt folder creation and routing
  • Workspace configuration inheritance
  • Cross-workspace synchronization
  • Template-based organization patterns

Communication Architecture

HTTP Bridge Protocol

The C# and Python components communicate via a RESTful HTTP API:

POST /api/clipboard/process
POST /api/triggers/execute  
POST /api/smrthub/update
GET  /api/status/health
GET  /api/config/workspace
PUT  /api/config/update

Heartbeat Monitoring

Comprehensive health monitoring across all components:

sequenceDiagram
    participant C as C# Components
    participant H as HTTP Bridge
    participant P as Python Core
    participant M as Monitoring

    loop Every 15-30 seconds
        C->>H: Heartbeat ping
        H->>P: Forward heartbeat
        P->>M: Update health status
        M->>H: Health response
        H->>C: Status confirmation
    end

Event Flow

Typical event processing flow through the system:

  1. Detection - ClipboardMonitor detects content change
  2. Analysis - Content sent to Python smrt detection
  3. Routing - SmrtSpace determines target location
  4. Processing - Content formatted and enhanced
  5. Saving - File saved with intelligent naming
  6. Feedback - SmrtHub shows completion status

Security and Performance

Security Features

  • Content Sanitization - All user content is sanitized to prevent injection attacks
  • Local-only Communication - HTTP bridge restricted to localhost
  • File System Permissions - Restricted file access based on configuration
  • Process Isolation - Components run in separate processes for stability

Performance Optimizations

  • Background Processing - Non-blocking save queue with worker threads
  • Intelligent Caching - Smrt caching of detection results and metadata
  • Efficient File I/O - Streaming operations for large files
  • Memory Management - Careful resource cleanup and garbage collection

Integration Points

Browser Extensions

  • Chrome, Firefox, Edge support via SmrtBrowsers/
  • WebSocket integration for real-time content capture
  • Native messaging for secure communication

External Applications

  • Microsoft Office integration via COM
  • Adobe application monitoring and parsing
  • Generic application content capture via Win32 API

Cloud Services (Future)

  • OneDrive/SharePoint synchronization
  • Google Drive integration
  • Dropbox and other cloud storage providers

Development Workflow

Build Process

  1. C# Build - MSBuild compilation of all .NET projects
  2. Python Setup - Virtual environment and dependency installation
  3. Integration Testing - Component communication verification
  4. Documentation Build - MkDocs documentation generation

Testing Strategy

  • Unit Tests - Individual component testing
  • Integration Tests - Cross-component communication testing
  • End-to-End Tests - Full workflow automation testing
  • Performance Tests - Load and stress testing

Deployment

  • Portable Installation - Self-contained deployment package
  • Configuration Migration - Automated settings transfer into the current schema
  • Version Management - Forward-only configuration migrations that drop obsolete formats

Future Roadmap

Planned Features

  • Multi-platform Support - macOS and Linux compatibility
  • Advanced AI Integration - Enhanced content analysis and suggestions
  • Cloud Synchronization - Multi-device workspace synchronization
  • Plugin Architecture - Third-party extension support
  • Mobile Companion - Mobile app for remote monitoring and control

Technical Improvements

  • Performance Optimization - Faster content processing and detection
  • UI Enhancement - Modern, responsive configuration interfaces
  • API Expansion - Extended REST API for third-party integration
  • Documentation - Interactive API documentation and examples