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

250 lines
12 KiB
Markdown
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
```mermaid
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.dmg`) 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`:
```objc
@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