Skip to content

WORKFLOW_DIAGRAM.md

Latest commit

 

History

History
555 lines (464 loc) · 17.9 KB

WORKFLOW_DIAGRAM.md

File metadata and controls

555 lines (464 loc) · 17.9 KB

oaDeviceAPI Workflow Architecture Diagrams

Purpose: Comprehensive architectural documentation for the unified device API system Status: ✅ Production Ready - October 2025 Handover Platform: Unified macOS and OrangePi Device API

System Overview

The oaDeviceAPI is a unified platform-agnostic service that automatically detects the underlying operating system (macOS or OrangePi/Ubuntu) and loads appropriate functionality through a modular architecture. This design enables single codebase deployment across diverse hardware platforms while maintaining platform-specific capabilities.

High-Level Architecture

%%{init: {
  'theme': 'base',
  'themeVariables': {
    'primaryColor': '#1f2937',
    'primaryTextColor': '#f8fafc',
    'primaryBorderColor': '#374151',
    'lineColor': '#6b7280',
    'sectionBkgColor': '#374151',
    'altSectionBkgColor': '#1f2937',
    'gridColor': '#4b5563',
    'secondaryColor': '#1e293b',
    'tertiaryColor': '#18181b',
    'textColor': '#f1f5f9',
    'edgeLabelBackground': '#374151',
    'clusterBkg': '#374151',
    'clusterBorder': '#6b7280',
    'titleColor': '#f8fafc'
  }
}}%%
graph TB
    subgraph "oaDeviceAPI Unified Service"
        API[FastAPI Application<br/>Port 9090]

        subgraph "Core Framework"
            Config[Configuration Manager]
            Platform[Platform Detection]
            Logging[Logging System]
            Cache[Caching Layer]
        end

        subgraph "Platform Abstraction"
            MacOS[macOS Platform<br/>Mac Mini]
            OrangePi[OrangePi Platform<br/>OrangePi 5B]
            Linux[Generic Linux<br/>Fallback]
        end

        subgraph "Unified Features"
            Health[Health Monitoring]
            Actions[System Actions]
            Security[Tailscale Security]
        end
    end

    subgraph "External Services"
        oaDashboard[oaDashboard<br/>Central Management]
        oaTracker[oaTracker<br/>Human Detection]
        CamGuard[CamGuard<br/>Recording Service]
        Player[Video Player<br/>OrangePi Only]
        Ansible[oaAnsible<br/>Deployment]
    end

    API --> Config
    API --> Platform
    API --> Logging
    API --> Cache

    Platform --> MacOS
    Platform --> OrangePi
    Platform --> Linux

    MacOS --> Health
    OrangePi --> Health
    Linux --> Health

    MacOS --> Actions
    OrangePi --> Actions

    API --> Security

    oaDashboard -.->|HTTP API| API
    Ansible -.->|Deploys| API
    oaTracker -.->|Integration| MacOS
    CamGuard -.->|Integration| MacOS
    Player -.->|Control| OrangePi

    classDef platformBox fill:#10b981,stroke:#059669,color:#f8fafc
    classDef serviceBox fill:#3b82f6,stroke:#2563eb,color:#f8fafc
    classDef coreBox fill:#f59e0b,stroke:#d97706,color:#f8fafc
    classDef externalBox fill:#6366f1,stroke:#4f46e5,color:#f8fafc

    class MacOS,OrangePi,Linux platformBox
    class Health,Actions,Security serviceBox
    class Config,Platform,Logging,Cache coreBox
    class oaDashboard,oaTracker,CamGuard,Player,Ansible externalBox
Loading

Platform Detection Flow

%%{init: {
  'theme': 'base',
  'themeVariables': {
    'primaryColor': '#1f2937',
    'primaryTextColor': '#f8fafc',
    'lineColor': '#10b981',
    'sectionBkgColor': '#374151',
    'altSectionBkgColor': '#1e293b',
    'titleColor': '#f8fafc'
  }
}}%%
flowchart TD
    Start([Application Startup]) --> Validate{Validate Python 3.12+}
    Validate -->|Success| Detect[Platform Detection]
    Validate -->|Failure| Fail[Exit with Error]

    Detect --> CheckMac{Is macOS?}
    CheckMac -->|Yes| LoadMac[Load macOS Router]
    CheckMac -->|No| CheckOP{Is OrangePi?}

    CheckOP -->|Yes| LoadOP[Load OrangePi Router]
    CheckOP -->|No| LoadLinux[Load Generic Linux Router]

    LoadMac --> FeaturesMac[macOS Features:<br/>• Camera Streaming<br/>• Tracker Integration<br/>• CamGuard Recording<br/>• SMC Temperature]
    LoadOP --> FeaturesOP[OrangePi Features:<br/>• Screenshots<br/>• Player Control<br/>• Display Management]
    LoadLinux --> FeaturesLinux[Linux Features:<br/>• Basic Health<br/>• System Actions]

    FeaturesMac --> StartServer[Start FastAPI Server<br/>Port 9090]
    FeaturesOP --> StartServer
    FeaturesLinux --> StartServer

    StartServer --> Ready[Service Ready]

    classDef successBox fill:#10b981,stroke:#059669,color:#f8fafc
    classDef failBox fill:#ef4444,stroke:#dc2626,color:#f8fafc
    classDef processBox fill:#3b82f6,stroke:#2563eb,color:#f8fafc
    classDef featureBox fill:#f59e0b,stroke:#d97706,color:#f8fafc

    class Ready,LoadMac,LoadOP,LoadLinux,StartServer successBox
    class Fail failBox
    class Validate,Detect,CheckMac,CheckOP processBox
    class FeaturesMac,FeaturesOP,FeaturesLinux featureBox
Loading

API Endpoint Architecture

%%{init: {
  'theme': 'base',
  'themeVariables': {
    'primaryColor': '#1f2937',
    'primaryTextColor': '#f8fafc',
    'lineColor': '#6b7280',
    'sectionBkgColor': '#374151',
    'altSectionBkgColor': '#1e293b',
    'titleColor': '#f8fafc'
  }
}}%%
graph LR
    subgraph "Core Endpoints<br/>All Platforms"
        Core["Root Endpoint<br>/"]
        Platform["Platform Endpoint<br>/platform"]
        Health["Health Endpoint<br>/health"]
        Reboot["Reboot Action<br>/actions/reboot"]
    end

    subgraph "macOS Platform<br/>Port 9090"
        MacOSRoot["macOS Root<br>/macos"]
        MacOSHealth["macOS Health<br>/macos/health"]
        Cameras["Cameras List<br>/macos/cameras"]
        Stream["Camera Stream<br>/macos/cameras/{id}/stream"]
        Tracker["Tracker Status<br>/macos/tracker/status"]
        CamGuard["CamGuard Status<br>/macos/camguard/status"]
        RestartTracker["Restart Tracker<br>/macos/actions/restart-tracker"]
    end

    subgraph "OrangePi Platform<br/>Port 9090"
        OPRoot["OrangePi Root<br>/orangepi"]
        OPHealth["OrangePi Health<br>/orangepi/health"]
        Screenshot["Screenshot<br>/orangepi/screenshot"]
        Player["Player Status<br>/orangepi/player/status"]
        RestartPlayer["Restart Player<br>/orangepi/player/actions/restart"]
    end

    subgraph "Generic Linux<br/>Fallback"
        LinuxRoot["Linux Root<br>/orangepi"]
        LinuxHealth["Linux Health<br>/orangepi/health"]
        LinuxActions["Linux Actions<br>/orangepi/actions/reboot"]
    end

    Core --> Platform
    Platform --> Health
    Health --> Reboot

    Platform --> MacOSRoot
    MacOSRoot --> MacOSHealth
    MacOSHealth --> Cameras
    Cameras --> Stream
    MacOSHealth --> Tracker
    MacOSHealth --> CamGuard
    CamGuard --> RestartTracker

    Platform --> OPRoot
    OPRoot --> OPHealth
    OPHealth --> Screenshot
    OPHealth --> Player
    Player --> RestartPlayer

    Platform -.->|Fallback| LinuxRoot
    LinuxRoot --> LinuxHealth
    LinuxHealth --> LinuxActions

    classDef coreEndpoint fill:#10b981,stroke:#059669,color:#f8fafc
    classDef macosEndpoint fill:#3b82f6,stroke:#2563eb,color:#f8fafc
    classDef orangePiEndpoint fill:#f59e0b,stroke:#d97706,color:#f8fafc
    classDef linuxEndpoint fill:#6b757d,stroke:#4b5563,color:#f8fafc

    class Core,Platform,Health,Reboot coreEndpoint
    class MacOSRoot,MacOSHealth,Cameras,Stream,Tracker,CamGuard,RestartTracker macosEndpoint
    class OPRoot,OPHealth,Screenshot,Player,RestartPlayer orangePiEndpoint
    class LinuxRoot,LinuxHealth,LinuxActions linuxEndpoint
Loading

Data Flow Architecture

%%{init: {
  'theme': 'base',
  'themeVariables': {
    'primaryColor': '#1f2937',
    'primaryTextColor': '#f8fafc',
    'lineColor': '#10b981',
    'sectionBkgColor': '#374151',
    'altSectionBkgColor': '#1e293b',
    'titleColor': '#f8fafc'
  }
}}%%
flowchart TB
    subgraph "Data Sources"
        Hardware[Hardware Sensors<br/>CPU, Memory, Disk]
        Camera[Camera Hardware<br/>macOS Only]
        Display[Display System<br/>OrangePi Only]
        Services[System Services<br/>launchctl/systemd]
    end

    subgraph "oaDeviceAPI Processing"
        subgraph "Platform Layer"
            PlatformAbstraction[Platform Abstraction<br/>platform_manager]
            FeatureDetection[Feature Detection<br/>Dynamic Loading]
        end

        subgraph "Service Layer"
            HealthService[Health Service<br/>Metrics Collection]
            CameraService[Camera Service<br/>Streaming/MJPEG]
            ScreenshotService[Screenshot Service<br/>Display Capture]
            ActionService[Action Service<br/>System Control]
        end

        subgraph "API Layer"
            FastAPI[FastAPI Router<br/>Endpoint Management]
            Middleware[Security Middleware<br/>Tailscale Filtering]
            Validation[Request Validation<br/>Pydantic Models]
        end
    end

    subgraph "Data Consumers"
        Dashboard[oaDashboard<br/>Central Monitoring]
        Monitoring[Health Monitoring<br/>Alerting System]
        Automation[Ansible<br/>Automation]
    end

    Hardware --> PlatformAbstraction
    Camera --> PlatformAbstraction
    Display --> PlatformAbstraction
    Services --> PlatformAbstraction

    PlatformAbstraction --> FeatureDetection
    FeatureDetection --> HealthService
    FeatureDetection --> CameraService
    FeatureDetection --> ScreenshotService
    FeatureDetection --> ActionService

    HealthService --> FastAPI
    CameraService --> FastAPI
    ScreenshotService --> FastAPI
    ActionService --> FastAPI

    FastAPI --> Middleware
    Middleware --> Validation
    Validation --> Dashboard
    Validation --> Monitoring
    Validation --> Automation

    classDef dataSource fill:#10b981,stroke:#059669,color:#f8fafc
    classDef platformLayer fill:#3b82f6,stroke:#2563eb,color:#f8fafc
    classDef serviceLayer fill:#f59e0b,stroke:#d97706,color:#f8fafc
    classDef apiLayer fill:#8b5cf6,stroke:#7c3aed,color:#f8fafc
    classDef consumer fill:#06b6d4,stroke:#0891b2,color:#f8fafc

    class Hardware,Camera,Display,Services dataSource
    class PlatformAbstraction,FeatureDetection platformLayer
    class HealthService,CameraService,ScreenshotService,ActionService serviceLayer
    class FastAPI,Middleware,Validation apiLayer
    class Dashboard,Monitoring,Automation consumer
Loading

Integration Patterns

oaDashboard Integration

%%{init: {
  'theme': 'base',
  'themeVariables': {
    'primaryColor': '#1f2937',
    'primaryTextColor': '#f8fafc',
    'lineColor': '#10b981',
    'sectionBkgColor': '#374151',
    'altSectionBkgColor': '#1e293b',
    'titleColor': '#f8fafc'
  }
}}%%
sequenceDiagram
    participant Dashboard as oaDashboard
    participant API as oaDeviceAPI
    participant Platform as Platform Layer

    Note over Dashboard,Platform: Device Discovery Flow

    Dashboard->>API: GET /platform
    API->>Platform: Detect platform
    Platform-->>API: {"platform": "macos", "features": {...}}
    API-->>Dashboard: Platform response

    Note over Dashboard,Platform: Health Monitoring Flow

    Dashboard->>API: GET /health
    API->>Platform: Get health metrics
    Platform-->>API: Raw health data
    API-->>Dashboard: Processed health response

    Note over Dashboard,Platform: Platform-Specific Features

    alt macOS Device
        Dashboard->>API: GET /macos/cameras
        API-->>Dashboard: Available cameras
        Dashboard->>API: GET /macos/tracker/status
        API-->>Dashboard: Tracker service status
    else OrangePi Device
        Dashboard->>API: GET /orangepi/screenshot
        API-->>Dashboard: Display screenshot
        Dashboard->>API: GET /orangepi/player/status
        API-->>Dashboard: Player status
    end
Loading

Security Architecture

%%{init: {
  'theme': 'base',
  'themeVariables': {
    'primaryColor': '#1f2937',
    'primaryTextColor': '#f8fafc',
    'lineColor': '#ef4444',
    'sectionBkgColor': '#374151',
    'altSectionBkgColor': '#1e293b',
    'titleColor': '#f8fafc'
  }
}}%%
graph TB
    subgraph "Security Layers"
        subgraph "Network Security"
            Tailscale[Tailscale VPN<br/>Private Network]
            Subnet[Subnet Restrictions<br/>100.x.x.x/8]
            Firewall[System Firewall<br/>Port 9090 Only]
        end

        subgraph "Application Security"
            Middleware[Security Middleware<br/>Request Filtering]
            CORS[CORS Configuration<br/>Domain Restrictions]
            Validation[Input Validation<br/>Pydantic Models]
        end

        subgraph "Platform Security"
            Service[Service Permissions<br/>launchctl/systemd]
            Sudo[Sudo Requirements<br/>Controlled Access]
            FileSystem[File System Access<br/>Restricted Paths]
        end
    end

    subgraph "External Access"
        oaDashboard[oaDashboard<br/>Trusted Client]
        Ansible[oaAnsible<br/>Deployment Tool]
        Monitoring[Monitoring<br/>Health Checks]
    end

    oaDashboard --> Tailscale
    Ansible --> Tailscale
    Monitoring --> Tailscale

    Tailscale --> Subnet
    Subnet --> Firewall
    Firewall --> Middleware
    Middleware --> CORS
    CORS --> Validation
    Validation --> Service
    Service --> Sudo
    Sudo --> FileSystem

    classDef networkSecurity fill:#10b981,stroke:#059669,color:#f8fafc
    classDef appSecurity fill:#3b82f6,stroke:#2563eb,color:#f8fafc
    classDef platformSecurity fill:#f59e0b,stroke:#d97706,color:#f8fafc
    classDef external fill:#6366f1,stroke:#4f46e5,color:#f8fafc

    class Tailscale,Subnet,Firewall networkSecurity
    class Middleware,CORS,Validation appSecurity
    class Service,Sudo,FileSystem platformSecurity
    class oaDashboard,Ansible,Monitoring external
Loading

Deployment Architecture

%%{init: {
  'theme': 'base',
  'themeVariables': {
    'primaryColor': '#1f2937',
    'primaryTextColor': '#f8fafc',
    'lineColor': '#10b981',
    'sectionBkgColor': '#374151',
    'altSectionBkgColor': '#1e293b',
    'titleColor': '#f8fafc'
  }
}}%%
graph TB
    subgraph "Development Environment"
        Dev[Development<br/>Local Testing]
        DevConfig[Development Config<br/>Debug Logging]
        DevReload[Auto-Reload<br/>Code Changes]
    end

    subgraph "Deployment Pipeline"
        Git[Git Repository<br/>oaDeviceAPI]
        Ansible[oaAnsible<br/>IaC Deployment]
        Config[Configuration<br/>Environment Vars]
    end

    subgraph "Target Platforms"
        subgraph "macOS Deployment"
            MacMini[Mac Mini<br/>Device Node]
            LaunchAgent[LaunchAgent<br/>User Service]
            MacOSBinary[macOS Binaries<br/>smctemp]
        end

        subgraph "OrangePi Deployment"
            OrangePi[OrangePi 5B<br/>Device Node]
            SystemD[SystemD Service<br/>System Service]
            LinuxBinary[Linux Tools<br/>System Utils]
        end
    end

    subgraph "Service Management"
        Monitoring[Service Monitoring<br/>Health Checks]
        Logs[Log Collection<br/>Centralized]
        Updates[Service Updates<br/>Rolling Deploy]
    end

    Dev --> Git
    Git --> Ansible
    Ansible --> Config
    Config --> MacMini
    Config --> OrangePi

    MacMini --> LaunchAgent
    OrangePi --> SystemD

    LaunchAgent --> MacOSBinary
    SystemD --> LinuxBinary

    MacMini --> Monitoring
    OrangePi --> Monitoring
    Monitoring --> Logs
    Logs --> Updates

    classDef devEnv fill:#8b5cf6,stroke:#7c3aed,color:#f8fafc
    classDef pipeline fill:#3b82f6,stroke:#2563eb,color:#f8fafc
    classDef platform fill:#10b981,stroke:#059669,color:#f8fafc
    classDef management fill:#f59e0b,stroke:#d97706,color:#f8fafc

    class Dev,DevConfig,DevReload devEnv
    class Git,Ansible,Config pipeline
    class MacMini,LaunchAgent,MacOSBinary,OrangePi,SystemD,LinuxBinary platform
    class Monitoring,Logs,Updates management
Loading

Component Interaction Matrix

Component oaDashboard oaAnsible oaTracker CamGuard Video Player
Health Monitoring ✅ Primary Consumer ✅ Deployment Validation ❌ ❌ ❌
Platform Detection ✅ UI Adaptation ✅ Platform Setup ❌ ❌ ❌
Camera Streaming ✅ Live View ❌ ✅ Model Input ✅ Recording ❌
System Actions ✅ Remote Control ✅ Service Management ❌ ❌ ✅ Restart
Screenshot Capture ✅ Device Status ❌ ❌ ❌ ✅ Content
Service Status ✅ Health Dashboard ✅ Deployment Health ✅ Process Status ✅ Recording Status ✅ Playback Status

Performance Considerations

Caching Strategy

  • Health Metrics: 30-second cache for system metrics
  • Platform Detection: Cached at startup (immutable)
  • Camera Status: 5-second cache for device availability
  • Service Status: Real-time (no caching)

Concurrency Patterns

  • Async/Await: All I/O operations use async patterns
  • Connection Pooling: HTTP clients use connection pooling
  • Resource Limits: Built-in rate limiting for expensive operations
  • Timeout Management: Configurable timeouts for all external calls

Resource Management

  • Memory Usage: Efficient Pydantic models with minimal overhead
  • CPU Usage: Non-blocking operations with proper error handling
  • Disk I/O: Streaming responses for camera feeds
  • Network: Optimized JSON responses with compression

Troubleshooting Flow Patterns

Service Not Starting

  1. Python Version: Verify Python 3.12+ installed
  2. Dependencies: Check uv.lock and run uv sync
  3. Platform Detection: Examine logs for platform detection errors
  4. Port Availability: Ensure port 9090 is not in use
  5. Permissions: Verify appropriate system permissions

Platform-Specific Issues

  • macOS: Check launchctl service status and SMC binary permissions
  • OrangePi: Verify systemd service status and display access
  • Linux: Fallback mode with limited functionality

Integration Problems

  • Network: Verify Tailscale connectivity and subnet restrictions
  • Authentication: Check service credentials and API tokens
  • Configuration: Validate environment variables and config files
  • Dependencies: Ensure required services (tracker, camguard) are running

Documentation Version: 1.0 Last Updated: October 2025 Handover Status: ✅ Complete Next Review: As needed during deployment