gronod/MacMonitor
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 2 Wiki Activity
Files
feat/12-process-details
MacMonitor/BUILD-PLAN.md
T

12 KiB
Raw Permalink Blame History

MacMonitor: Deterministic Master Build Plan

1. Project Specifications & Architectural Constraints

  • Platform Target: macOS for Intel (x86_64).
  • Minimum OS Version: macOS 14.0 (Sonoma) or higher.
  • Language Stack: SwiftUI (Presentation & ViewModels) + Objective-C / C (Low-level Mach, IOKit, SMC, BSD Sysctl APIs).
  • Interoperability: Modular Objective-C bridging layer (MacMonitor-Bridging-Header.h) exposing thread-safe C primitives to Swift.
  • CI/CD Platform: Gitea Actions executing on Intel macOS runners ([macos, intel]).
  • Target Hardware Spectrum: Intel-based MacBook (Air/Pro), iMac, Mac mini, and Mac Pro (2019/Rack).

2. Deterministic Git Branching Strategy & Naming Conventions

2.1 Branch Taxonomy

All development follows a strict GitFlow-inspired branching model with deterministic naming:

Branch Role Branch Pattern Source Branch Merge Target Description
Production main N/A N/A Production-ready releases tagged with SemVer (v1.0.0).
Integration develop main main Primary active development and staging integration branch.
Milestone milestone/m<N>-<slug> develop develop Milestone stabilization branch grouping dependent features.
Feature feat/<issue#>-<slug> milestone/m<N>-... milestone/m<N>-... Isolated feature development branch tied directly to Gitea issue.
Bugfix fix/<issue#>-<slug> develop or main develop or main Defect resolution branch.

2.2 Deterministic Feature Branch Directory

Issue # Feature Title Milestone Exact Branch Name
#1 Core Application Architecture & Bridging M1 feat/1-core-architecture
#2 SMC Interface Engine (AppleSMC Client) M1 feat/2-smc-client
#25 Gitea Actions CI/CD Pipeline M1 feat/25-gitea-ci
#3 CPU Core Temperatures & Thermal Zones M2 feat/3-cpu-thermals
#4 Fan Speed & Multi-Fan Telemetry M2 feat/4-fan-telemetry
#5 Host CPU Core Utilization & Frequency M2 feat/5-cpu-load
#8 RAM Breakdown, Compression & Pressure M2 feat/8-ram-breakdown
#9 Storage Volumes & APFS Containers M2 feat/9-storage-volumes
#18 Motherboard, PCH & Heatsink Temps M2 feat/18-component-temps
#19 Power Consumption, Voltage & Current M2 feat/19-power-voltage
#6 Kernel Context Switching & Syscalls M3 feat/6-kernel-counters
#7 System Load Averages & Concurrency M3 feat/7-load-averages
#10 Real-Time Disk I/O & IOPS Telemetry M3 feat/10-disk-io
#11 Live Process Explorer & Table M3 feat/11-process-explorer
#12 Per-Process Threads & File Descriptors M3 feat/12-process-threads
#14 Intel iGPU & AMD Discrete GPU Telemetry M3 feat/14-gpu-telemetry
#15 Real-Time Network Bandwidth M3 feat/15-network-throughput
#16 Active Network Sockets Inspector M3 feat/16-network-sockets
#17 MacBook Battery & Power Adapter M3 feat/17-battery-telemetry
#20 Connected Peripherals & Bus Topology M3 feat/20-bus-topology
#21 Audio Devices & Volume Monitor M3 feat/21-audio-status
#13 Screen Brightness & Display Management M4 feat/13-display-brightness
#22 Status Bar Menu Bar Extra & Popover M4 feat/22-menubar-popover
#23 Historical Rolling Trend Charts M4 feat/23-trend-charts
#24 Threshold Alerts & macOS Notifications M5 feat/24-threshold-alerts

3. Milestone Breakdown & Implementation Sequences

graph TD
    classDef m1 fill:#dbeafe,stroke:#1d4ed8,stroke-width:2px;
    classDef m2 fill:#dcfce7,stroke:#15803d,stroke-width:2px;
    classDef m3 fill:#fef3c7,stroke:#b45309,stroke-width:2px;
    classDef m4 fill:#f3e8ff,stroke:#7e22ce,stroke-width:2px;
    classDef m5 fill:#fee2e2,stroke:#b91c1c,stroke-width:2px;

    %% M1 Foundation
    I1["#1 Core Architecture"]:::m1
    I2["#2 AppleSMC Client"]:::m1
    I25["#25 Gitea CI/CD Pipeline"]:::m1

    I1 --> I2
    I1 --> I25

    %% M2 Primary Telemetry
    I5["#5 CPU Core Utilization"]:::m2
    I8["#8 RAM & Memory Pressure"]:::m2
    I9["#9 Storage Volumes"]:::m2
    I3["#3 CPU Core Temps"]:::m2
    I4["#4 Fan Speeds"]:::m2
    I18["#18 Component Temps"]:::m2
    I19["#19 Power & Voltage"]:::m2

    I1 --> I5
    I1 --> I8
    I1 --> I9
    I2 --> I3
    I2 --> I4
    I2 --> I18
    I2 --> I19

    %% M3 Advanced Telemetry
    I6["#6 Kernel Counters"]:::m3
    I7["#7 Load Averages"]:::m3
    I10["#10 Disk I/O & IOPS"]:::m3
    I11["#11 Process Explorer"]:::m3
    I12["#12 Thread/FD Details"]:::m3
    I14["#14 GPU Telemetry"]:::m3
    I15["#15 Network Bandwidth"]:::m3
    I16["#16 Socket Inspector"]:::m3
    I17["#17 Battery Telemetry"]:::m3
    I20["#20 Peripheral Bus"]:::m3
    I21["#21 Audio Devices"]:::m3

    I1 --> I6
    I1 --> I7
    I9 --> I10
    I1 --> I11
    I11 --> I12
    I1 --> I14
    I1 --> I15
    I11 --> I16
    I15 --> I16
    I1 --> I17
    I1 --> I20
    I1 --> I21

    %% M4 Presentation
    I13["#13 Display Brightness"]:::m4
    I22["#22 MenuBar & Popover"]:::m4
    I23["#23 Swift Trend Charts"]:::m4

    I1 --> I13
    I1 --> I22
    I1 --> I23

    %% M5 Intelligence
    I24["#24 Alerts & Notifications"]:::m5
    I3 --> I24
    I4 --> I24
    I8 --> I24
    I9 --> I24

Milestone 1: Architecture Foundation & Hardware Abstraction

  • Integration Branch: milestone/m1-foundation
  • Goal: Deliver the Objective-C bridging layer, central telemetry coordinator, AppleSMC IOKit driver, and Gitea Actions Intel runner CI.
  • Execution Order:
    1. Phase 1.1 (Sequential Anchor): #1 Core Architecture (feat/1-core-architecture). Establish project structure, bridging header, and base MMTelemetryProvider protocol.
    2. Phase 1.2 (Parallel Tracks):
      • Track 1.2A: #2 AppleSMC Client (feat/2-smc-client). Low-level SMC key reader, data parsers (sp78, fpe2, flt).
      • Track 1.2B: #25 Gitea CI/CD Pipeline (feat/25-gitea-ci). Create .gitea/workflows/build.yml targeting Intel runners.
  • Quality Gate M1: Successful build and execution of sample test suite on Gitea Actions runner compiling for x86_64 macOS 14.

Milestone 2: Primary System & Thermal Telemetry

  • Integration Branch: milestone/m2-primary-telemetry
  • Goal: Core hardware and OS resource telemetry (CPU, thermals, fans, memory, storage volumes, power).
  • Execution Order (Parallel Tracks):
    • Track 2A (OS & Kernel Track - Depends on #1):
      • #5 Host CPU Core Utilization (feat/5-cpu-load)
      • #8 RAM Breakdown & Memory Pressure (feat/8-ram-breakdown)
      • #9 Storage Volumes & APFS Containers (feat/9-storage-volumes)
    • Track 2B (SMC Hardware Track - Depends on #2):
      • #3 CPU Core Temperatures (feat/3-cpu-thermals)
      • #4 Fan Speed Telemetry (feat/4-fan-telemetry)
      • #18 Component & Heatsink Temperatures (feat/18-component-temps)
      • #19 Power & Voltage Telemetry (feat/19-power-voltage)
  • Quality Gate M2: All 7 providers reporting valid telemetry concurrently in a unified sample loop without memory leaks or race conditions.

Milestone 3: Advanced Kernel, Process & Peripheral Telemetry

  • Integration Branch: milestone/m3-advanced-telemetry
  • Goal: Granular process inspection, storage throughput, network bandwidth, GPU, and peripheral buses.
  • Execution Order (Parallel Tracks):
    • Track 3A (Process & Concurrency Subsystem):
      • #6 Kernel Context Switching & Syscalls (feat/6-kernel-counters)
      • #7 System Load Averages (feat/7-load-averages)
      • #11 Live Process Explorer (feat/11-process-explorer)
      • #12 Per-Process Threads & File Descriptors (feat/12-process-threads - Depends on #11)
    • Track 3B (I/O & Networking Subsystem):
      • #10 Real-Time Disk I/O & IOPS (feat/10-disk-io - Depends on #9)
      • #15 Real-Time Network Bandwidth (feat/15-network-throughput)
      • #16 Active Network Sockets (feat/16-network-sockets - Depends on #11 and #15)
    • Track 3C (Graphics, Power & Peripherals):
      • #14 Intel iGPU & AMD dGPU Telemetry (feat/14-gpu-telemetry)
      • #17 MacBook Battery Telemetry (feat/17-battery-telemetry)
      • #20 Connected Peripherals & Bus Topology (feat/20-bus-topology)
      • #21 Audio Devices & Volume Monitor (feat/21-audio-status)
  • Quality Gate M3: High-volume process and socket enumeration running smoothly under stress without UI hitching or exceeding 2% background CPU load.

Milestone 4: Presentation, Visuals & Menu Bar Integration

  • Integration Branch: milestone/m4-presentation
  • Goal: User-facing presentation layer: macOS 14 Menu Bar Extra, popover widgets, display brightness management, and Swift Charts rolling graphs.
  • Execution Order:
    1. #13 Screen Brightness & Display Management (feat/13-display-brightness)
    2. #22 Status Bar Menu Bar Extra & Popover (feat/22-menubar-popover)
    3. #23 Historical Rolling Trend Charts (feat/23-trend-charts)
  • Quality Gate M4: Menu bar and popover views maintain 60 FPS animation during telemetry refreshes; smooth dark/light mode transitions.

Milestone 5: Intelligence, Alerts & Hardening

  • Integration Branch: milestone/m5-alerts-hardening
  • Goal: Proactive health alerts, macOS Notification Center integration, end-to-end regression validation, and release packaging.
  • Execution Order:
    1. #24 Threshold Alerts & Notification Center (feat/24-threshold-alerts - Depends on #3, #4, #8, #9)
    2. Full end-to-end integration testing and automated release archiving (MacMonitor-intel-x86_64.zip) on tagged commit.
  • Quality Gate M5: Zero crashes, all unit test suites passing on Intel macOS runner, DMG/ZIP distribution artifact ready.

4. Parallel Stage Interaction Contracts

To allow independent development across parallel tracks, modules adhere to three immutable interaction contracts:

4.1 Provider Contract (MMTelemetryProvider)

Every data provider must conform to MMTelemetryProvider:

@protocol MMTelemetryProvider <NSObject>
@property (nonatomic, readonly) MMTelemetryDomain domain;
@property (nonatomic, readonly, copy) NSString *providerIdentifier;
@property (nonatomic, readonly, getter=isAvailable) BOOL available;

- (nullable NSDictionary<NSString *, id> *)sampleTelemetryWithError:(NSError **)error;
@optional
- (void)startMonitoring;
- (void)stopMonitoring;
@end

4.2 Data Transfer Object (DTO) Contract

Providers emit read-only snapshot dictionaries on the background telemetry queue. Key schemas are strictly typed and documented in each issue's technical implementation notes. Swift view models ingest snapshots across the @MainActor boundary using value-type structs (Sendable).

4.3 Threading & Concurrency Contract

  • Sampling Thread: Exclusively executed on a serial Grand Central Dispatch queue (com.i3omb.macmonitor.telemetry, QoS: QOS_CLASS_UTILITY).
  • UI Store: State updates are dispatched to the @MainActor shared store (SystemTelemetryStore).
  • Mach Memory Safety: Every pointer allocated by Mach calls (host_processor_info, proc_listpids) must be deallocated in the same sampling tick using vm_deallocate or free.

5. Verification & Testing Matrix

Subsystem Automated Verification Manual / Hardware Verification
SMC & Sensors Mocked SMC binary byte-buffer parsing tests Verifying RPM and temperatures on MacBook and iMac
Mach Host CPU Math unit tests for tick delta calculations Verifying CPU load match against /usr/bin/top -l 1
Memory / VM Verifying formula app + wired + compressed vs total Comparison with macOS Activity Monitor Memory tab
Process Explorer PID lifecycle unit test with child spawn & termination Testing process filtering and termination confirmation
Network & Disk Loopback synthetic traffic generator test Verifying large file transfer throughput metrics
Build & CI Automated Gitea Actions build on macOS Intel runner Xcode Archive validation and .app gatekeeper testing
Reference in New Issue View Git Blame Copy Permalink