SPB Git

Repository Public License

overview.md 9.3 KB

# Architecture overview

ORIX Monitor is split in two layers:

  • ORIXMonitorCore — a Swift package (Packages/ORIXMonitorCore) with no SwiftUI or AppKit dependency. It contains the collectors, the sampling loop, the SQLite time-series store, the alert state machine, the findings detectors and the report model. It also builds a command-line executable, orix-probe.
  • The app (App/Sources) — SwiftUI scenes, a main-actor view model, the design system and the PDF renderer.

The package links IOKit, DiskArbitration, SystemConfiguration, CoreWLAN, Metal and libsqlite3 (see Package.swift). It has no third-party dependency, and neither has the app.

# Pipeline

flowchart LR
    subgraph SYS["System APIs"]
        A1["Mach host calls"]
        A2["sysctl"]
        A3["IOKit registry"]
        A4["libproc"]
        A5["IOPowerSources"]
        A6["ProcessInfo"]
    end
    subgraph CORE["ORIXMonitorCore"]
        C["Collectors"]
        N["Normalizer.values"]
        S["TimeSeriesStore"]
        AL["AlertEngine"]
        SP["ProcessSpikeTracker"]
        IE["IntelligenceEngine"]
        RG["ReportGenerator"]
    end
    subgraph APP["App"]
        M["MonitorModel"]
        UI["Main window pages"]
        MB["Menu bar extra"]
        RP["Reports and PDF"]
        NC["Notification Center"]
    end
    SYS --> C
    C --> N
    N --> S
    N --> AL
    C --> SP
    SP --> S
    AL --> S
    S --> IE
    S --> RG
    C --> M
    AL --> M
    IE --> M
    M --> UI
    M --> MB
    M --> NC
    RG --> RP

In words:

  1. Collectors read cumulative counters or instantaneous states from the system and turn them into typed samples (CPUSample, MemorySample, DiskActivitySample, NetworkSample, ProcessSample, PowerSample, ThermalLevel, [GPUStatistics]). Rates are computed against a monotonic clock. See collectors.
  2. Normalizer.values(...) flattens the samples into [MetricValue], one per MetricID that could actually be measured on this tick. A missing input produces no value, never a zero.
  3. The values go to three consumers inside TelemetryEngine.tick():
    • AlertEngine.evaluate(_:at:), which returns AlertTransitions (fired / resolved). See alerts.
    • TimeSeriesStore.append(_:at:), which buffers raw rows and rolls minute and hour aggregates. See storage.
    • A TelemetrySnapshot, yielded to every subscriber of TelemetryEngine.snapshots().
  4. MonitorModel (main actor, @Observable) consumes the snapshot stream, keeps a bounded in-memory window for live charts, relays firing rules, posts notifications and periodically asks the engine for findings.
  5. Findings are computed on demand from stored history by TelemetryEngine.findings(...) → IntelligenceEngine.analyse(_:thresholds:).
  6. Reports are built from stored series by ReportGenerator.build(_:formatter:localize:) and rendered to Markdown, CSV, JSON (core) or PDF (PDFReportRenderer, app). See reporting.

# One tick

sequenceDiagram
    participant L as Sampling loop
    participant E as TelemetryEngine
    participant C as Collectors
    participant A as AlertEngine
    participant S as TimeSeriesStore
    participant M as MonitorModel
    L->>E: tick
    E->>E: effective interval and discontinuity check
    E->>C: sample cpu, memory, disk, network, gpu, thermal
    E->>C: volumes and power if the slow tier is due
    E->>C: processes if the process tier is due
    C-->>E: typed samples
    E->>E: Normalizer.values
    E->>A: evaluate values at date
    A-->>E: transitions
    E->>S: record alert and spike events
    E->>S: append values if history is enabled
    E->>S: flush if 30 s elapsed
    E-->>M: yield TelemetrySnapshot
    E-->>L: seconds to wait

The loop is a single Task created in TelemetryEngine.start(); it calls tick(), then sleeps for the returned interval with a 10 % tolerance. Details in telemetry.

# Concurrency model

Component Isolation Notes
TelemetryEngine actor Owns the collectors, the AlertEngine value and the ProcessSpikeTracker value. Collectors are plain final classes touched only from this actor.
TimeSeriesStore actor Owns the SQLite handle through SQLiteConnection (closed in deinit). The database is opened with SQLITE_OPEN_FULLMUTEX.
AlertEngine, ProcessSpikeTracker struct, Sendable Pure state machines with no I/O.
IntelligenceEngine, Detectors, SeriesMath, CPUMath, MemoryMath, CounterMath, NetworkMath, DiskMath, ProcessMath, PowerMath, SchedulerMath, Normalizer, ReportGenerator caseless enums of static functions Pure; this is what the unit tests exercise.
MonitorModel, AppSettings @MainActor @Observable The only objects SwiftUI views read.
PDFReportRenderer @MainActor Core Graphics / Core Text drawing.

The project is built in Swift 6 language mode with SWIFT_STRICT_CONCURRENCY: complete (project.yml, Package.swift).

# App structure

ORIXMonitorApp declares four scenes:

Scene Purpose
Window("ORIX Monitor", id: "main") RootView: a NavigationSplitView with the sidebar (AppSection) and one detail page per section. Minimum 860 × 560, default 1280 × 860.
WindowGroup("Dashboard", id: "dashboard", for: UUID.self) Detached dashboard windows for a second display.
Settings SettingsView with six tabs: General, Sampling, History, Menu Bar, Privacy, About.
MenuBarExtra (.window style) MenuBarLabel (a template NSImage drawn by MenuBarRenderer) and MenuBarPanel. Inserted according to AppSettings.showMenuBar.

AppSection lists thirteen pages: Overview; Hardware — CPU, GPU, Memory, Disk, Network, Power, Thermal & Sensors; Analysis — Processes, History, Insights, Alerts, Reports.

Feature files:

File Views
Features/DashboardView.swift DashboardView, FlowGrid, WidgetView, shared helpers (MemoryBar, PressureBadge, ThermalScale, ThermalText, PowerText)
Features/ComputeViews.swift CPUView, GPUView, MemoryView
Features/SystemViews.swift DiskView, NetworkView, PowerView, ThermalView
Features/ProcessesView.swift ProcessesView (table, inspector, confirmed quit actions)
Features/HistoryView.swift HistoryView, HistoryChart
Features/AnalysisViews.swift InsightsView, AlertsView, RuleEditor, FindingText
Features/ReportsView.swift ReportsView, ReportTableView
Features/SettingsView.swift SettingsView and its tabs
Features/MenuBar.swift MenuBarRenderer, MenuBarLabel, MenuBarPanel

# MonitorModel responsibilities

  • Opens the store at <Application Support>/ORIX Monitor/telemetry.sqlite (or under -ORIXDataDir), and creates the engine. If the store cannot be opened, storeError is set and the engine runs with store == nil: live values keep working, nothing is persisted.
  • start() subscribes to engine.snapshots(), starts the loop, and registers observers:
    • NSWorkspace.willSleepNotification / didWakeNotification → engine.noteDiscontinuity(code:).
    • Power-state, thermal-state, volume mount and unmount notifications → engine.invalidateSlowReadings().
    • Window occlusion, close and key notifications → updateForeground() → engine.setForeground(_:).
    • An NWPathMonitor that records network.online / network.offline events.
  • ingest(_:) keeps at most liveCapacity = 150 points per metric and 150 per-core rows, trims the window to one point after a discontinuity, posts notifications for fired alerts, refreshes Wi-Fi and DNS every fifth snapshot, and refreshes findings every 300 s.
  • shutdown() cancels the stream and awaits engine.stop(), which flushes the store. AppDelegate.applicationShouldTerminate returns .terminateLater until this completes.
  • Process actions (perform(_:on:)): NSRunningApplication.terminate() or kill(SIGTERM) for Quit, kill(SIGKILL) for Force Quit; refused for PID ≤ 1 and for the app itself; offered in the UI only for processes owned by the current user and only behind a confirmation dialog.
  • Launch at login through SMAppService.mainApp.

# Data that never leaves the Mac

There is no networking code in the pipeline. The only outbound connection the app can make is NetworkCollector.measureLatency(host:port:attempts:timeout:), a TCP handshake to a host typed by the user, run when the "Run Test" button is pressed.

# Not implemented

  • No background daemon or login item separate from the app: history is recorded only while ORIX Monitor runs.
  • No privileged helper, no XPC service, no kernel or system extension.
  • No per-process history in the store. A short CPU/memory history (120 points) exists only in the Processes inspector for the selected process, in view state.
  • No remote monitoring, no export scheduler, no update mechanism.
  • TelemetryEngine.setProcessSampling(_:) exists but the app never calls it: the process table is sampled on its tier regardless of which page is visible.
  • IntelligenceThresholds is persisted by AppSettings and displayed on the Insights page, but no settings screen edits it.
Files main
Menu

Theme