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:
- 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. Normalizer.values(...)flattens the samples into[MetricValue], one perMetricIDthat could actually be measured on this tick. A missing input produces no value, never a zero.- The values go to three consumers inside
TelemetryEngine.tick(): 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.- Findings are computed on demand from stored history by
TelemetryEngine.findings(...)→IntelligenceEngine.analyse(_:thresholds:). - 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,storeErroris set and the engine runs withstore == nil: live values keep working, nothing is persisted. start()subscribes toengine.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
NWPathMonitorthat recordsnetwork.online/network.offlineevents.
ingest(_:)keeps at mostliveCapacity = 150points 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 awaitsengine.stop(), which flushes the store.AppDelegate.applicationShouldTerminatereturns.terminateLateruntil this completes.- Process actions (
perform(_:on:)):NSRunningApplication.terminate()orkill(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.IntelligenceThresholdsis persisted byAppSettingsand displayed on the Insights page, but no settings screen edits it.