Repository Public License
1<!--2ORIX Monitor3File: docs/architecture/overview.md4Author: Simon-Pierre Boucher5Contact: contact@spboucher.ai6-->78# Architecture overview910ORIX Monitor is split in two layers:1112- **`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`.13- **The app** (`App/Sources`) — SwiftUI scenes, a main-actor view model, the design system and the PDF renderer.1415The package links IOKit, DiskArbitration, SystemConfiguration, CoreWLAN, Metal and `libsqlite3` (see `Package.swift`). It has no third-party dependency, and neither has the app.1617## Pipeline1819```mermaid20flowchart LR21 subgraph SYS["System APIs"]22 A1["Mach host calls"]23 A2["sysctl"]24 A3["IOKit registry"]25 A4["libproc"]26 A5["IOPowerSources"]27 A6["ProcessInfo"]28 end29 subgraph CORE["ORIXMonitorCore"]30 C["Collectors"]31 N["Normalizer.values"]32 S["TimeSeriesStore"]33 AL["AlertEngine"]34 SP["ProcessSpikeTracker"]35 IE["IntelligenceEngine"]36 RG["ReportGenerator"]37 end38 subgraph APP["App"]39 M["MonitorModel"]40 UI["Main window pages"]41 MB["Menu bar extra"]42 RP["Reports and PDF"]43 NC["Notification Center"]44 end45 SYS --> C46 C --> N47 N --> S48 N --> AL49 C --> SP50 SP --> S51 AL --> S52 S --> IE53 S --> RG54 C --> M55 AL --> M56 IE --> M57 M --> UI58 M --> MB59 M --> NC60 RG --> RP61```6263In words:64651. **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](collectors.md).662. **`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.673. The values go to three consumers inside `TelemetryEngine.tick()`:68 - **`AlertEngine.evaluate(_:at:)`**, which returns `AlertTransition`s (fired / resolved). See [alerts](alerts.md).69 - **`TimeSeriesStore.append(_:at:)`**, which buffers raw rows and rolls minute and hour aggregates. See [storage](storage.md).70 - A **`TelemetrySnapshot`**, yielded to every subscriber of `TelemetryEngine.snapshots()`.714. **`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.725. **Findings** are computed on demand from stored history by `TelemetryEngine.findings(...)` → `IntelligenceEngine.analyse(_:thresholds:)`.736. **Reports** are built from stored series by `ReportGenerator.build(_:formatter:localize:)` and rendered to Markdown, CSV, JSON (core) or PDF (`PDFReportRenderer`, app). See [reporting](reporting.md).7475## One tick7677```mermaid78sequenceDiagram79 participant L as Sampling loop80 participant E as TelemetryEngine81 participant C as Collectors82 participant A as AlertEngine83 participant S as TimeSeriesStore84 participant M as MonitorModel85 L->>E: tick86 E->>E: effective interval and discontinuity check87 E->>C: sample cpu, memory, disk, network, gpu, thermal88 E->>C: volumes and power if the slow tier is due89 E->>C: processes if the process tier is due90 C-->>E: typed samples91 E->>E: Normalizer.values92 E->>A: evaluate values at date93 A-->>E: transitions94 E->>S: record alert and spike events95 E->>S: append values if history is enabled96 E->>S: flush if 30 s elapsed97 E-->>M: yield TelemetrySnapshot98 E-->>L: seconds to wait99```100101The 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](telemetry.md).102103## Concurrency model104105| Component | Isolation | Notes |106|---|---|---|107| `TelemetryEngine` | `actor` | Owns the collectors, the `AlertEngine` value and the `ProcessSpikeTracker` value. Collectors are plain `final class`es touched only from this actor. |108| `TimeSeriesStore` | `actor` | Owns the SQLite handle through `SQLiteConnection` (closed in `deinit`). The database is opened with `SQLITE_OPEN_FULLMUTEX`. |109| `AlertEngine`, `ProcessSpikeTracker` | `struct`, `Sendable` | Pure state machines with no I/O. |110| `IntelligenceEngine`, `Detectors`, `SeriesMath`, `CPUMath`, `MemoryMath`, `CounterMath`, `NetworkMath`, `DiskMath`, `ProcessMath`, `PowerMath`, `SchedulerMath`, `Normalizer`, `ReportGenerator` | caseless `enum`s of static functions | Pure; this is what the unit tests exercise. |111| `MonitorModel`, `AppSettings` | `@MainActor @Observable` | The only objects SwiftUI views read. |112| `PDFReportRenderer` | `@MainActor` | Core Graphics / Core Text drawing. |113114The project is built in Swift 6 language mode with `SWIFT_STRICT_CONCURRENCY: complete` (`project.yml`, `Package.swift`).115116## App structure117118`ORIXMonitorApp` declares four scenes:119120| Scene | Purpose |121|---|---|122| `Window("ORIX Monitor", id: "main")` | `RootView`: a `NavigationSplitView` with the sidebar (`AppSection`) and one detail page per section. Minimum 860 × 560, default 1280 × 860. |123| `WindowGroup("Dashboard", id: "dashboard", for: UUID.self)` | Detached dashboard windows for a second display. |124| `Settings` | `SettingsView` with six tabs: General, Sampling, History, Menu Bar, Privacy, About. |125| `MenuBarExtra` (`.window` style) | `MenuBarLabel` (a template `NSImage` drawn by `MenuBarRenderer`) and `MenuBarPanel`. Inserted according to `AppSettings.showMenuBar`. |126127`AppSection` lists thirteen pages: Overview; Hardware — CPU, GPU, Memory, Disk, Network, Power, Thermal & Sensors; Analysis — Processes, History, Insights, Alerts, Reports.128129Feature files:130131| File | Views |132|---|---|133| `Features/DashboardView.swift` | `DashboardView`, `FlowGrid`, `WidgetView`, shared helpers (`MemoryBar`, `PressureBadge`, `ThermalScale`, `ThermalText`, `PowerText`) |134| `Features/ComputeViews.swift` | `CPUView`, `GPUView`, `MemoryView` |135| `Features/SystemViews.swift` | `DiskView`, `NetworkView`, `PowerView`, `ThermalView` |136| `Features/ProcessesView.swift` | `ProcessesView` (table, inspector, confirmed quit actions) |137| `Features/HistoryView.swift` | `HistoryView`, `HistoryChart` |138| `Features/AnalysisViews.swift` | `InsightsView`, `AlertsView`, `RuleEditor`, `FindingText` |139| `Features/ReportsView.swift` | `ReportsView`, `ReportTableView` |140| `Features/SettingsView.swift` | `SettingsView` and its tabs |141| `Features/MenuBar.swift` | `MenuBarRenderer`, `MenuBarLabel`, `MenuBarPanel` |142143## `MonitorModel` responsibilities144145- 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.146- `start()` subscribes to `engine.snapshots()`, starts the loop, and registers observers:147 - `NSWorkspace.willSleepNotification` / `didWakeNotification` → `engine.noteDiscontinuity(code:)`.148 - Power-state, thermal-state, volume mount and unmount notifications → `engine.invalidateSlowReadings()`.149 - Window occlusion, close and key notifications → `updateForeground()` → `engine.setForeground(_:)`.150 - An `NWPathMonitor` that records `network.online` / `network.offline` events.151- `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.152- `shutdown()` cancels the stream and awaits `engine.stop()`, which flushes the store. `AppDelegate.applicationShouldTerminate` returns `.terminateLater` until this completes.153- 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.154- Launch at login through `SMAppService.mainApp`.155156## Data that never leaves the Mac157158There 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.159160## Not implemented161162- No background daemon or login item separate from the app: history is recorded only while ORIX Monitor runs.163- No privileged helper, no XPC service, no kernel or system extension.164- 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.165- No remote monitoring, no export scheduler, no update mechanism.166- `TelemetryEngine.setProcessSampling(_:)` exists but the app never calls it: the process table is sampled on its tier regardless of which page is visible.167- `IntelligenceThresholds` is persisted by `AppSettings` and displayed on the Insights page, but no settings screen edits it.168