Skip to content

Commit 1bd439f

Browse files
offyottooffyotto
committed
Add comprehensive Core-Monitor wiki
1 parent 4dc3880 commit 1bd439f

734 files changed

Lines changed: 47561 additions & 0 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎docs/wiki/App-Startup-And-Lifecycle.md‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
# App Startup And Lifecycle
2+
3+
Startup is controlled by `Core_MonitorApp.swift`, `WelcomeGuideProgress.swift`, `StartupManager.swift`, `DashboardShortcutManager.swift`, and `AppCoordinator.swift`.
4+
5+
The app must satisfy two conflicting goals: behave like a quiet menu bar utility for returning users, and show a visible dashboard/onboarding surface for first launch or explicit dashboard requests. The current delegate disables automatic termination, handles duplicate launches, purges deprecated defaults, determines welcome-guide presentation, installs global shortcuts/observers, creates menu bar items, and opens the dashboard if needed.
6+
7+
Activation policy matters. The app can be accessory-style for menu bar operation, but it must temporarily promote visibility when the dashboard is shown so the window does not vanish behind other apps or launch invisibly.
8+
9+
Shutdown is also functional: fan modes that Core-Monitor owns should be returned to system automatic best-effort before process exit. That cleanup is part of the trust model.

‎docs/wiki/Assets-And-Media.md‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
# Assets And Media
2+
3+
Assets include app icons, accent colors, Pock weather/status icons, website screenshots, Gatekeeper walkthrough images, videos, and Kernel Panic audio.
4+
5+
Several media files were replaced or removed across history, including old walkthrough videos, screenshots, MP3 soundtrack files replaced by M4A assets, and stale UI images.
6+
7+
Keep source-control size in mind. App bundles, DerivedData, module caches, and generated build products have been removed before and should stay out of normal commits.

‎docs/wiki/Battery-Power-And-Thermals.md‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
# Battery Power And Thermals
2+
3+
Battery data is modeled in `BatteryInfo` and formatted through `BatteryDetailFormatter`. Data includes charge, source, status, cycle count, health, voltage, amperage, power watts, temperature, capacities, and time remaining where macOS provides it.
4+
5+
Power data is used both for user-facing visibility and fan-control heuristics. Smart and custom fan modes can treat high watt draw as an effective temperature boost, which lets Core-Monitor respond to sustained load before raw temperature alone catches up.
6+
7+
Thermal readings come from SMC keys and ProcessInfo thermal state. The app must be honest about missing sensors: unsupported keys should show unavailable/fallback messaging rather than pretending exact measurements exist.

‎docs/wiki/CPU-GPU-Memory-Disk-Network.md‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
# CPU GPU Memory Disk Network
2+
3+
CPU load comes from host CPU counters and per-processor load info. Apple Silicon performance and efficiency core utilization uses logical-core grouping from sysctl when available.
4+
5+
GPU temperature is SMC-backed and depends on chip-specific keys. The app probes several known keys and falls back when a sensor is unavailable. GPU utilization is not the same as GPU temperature and should not be implied unless a real utilization source exists.
6+
7+
Memory stats come from VM statistics: used, wired, compressed, free, page-ins, page-outs, swap, and derived pressure. UI should explain pressure and swap in user terms, not only percentages.
8+
9+
Disk stats are gated because filesystem capacity and process-level disk activity do not need the same cadence as CPU load. Network throughput uses byte deltas over time, not a raw absolute counter.

‎docs/wiki/Custom-Fan-Curves.md‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
# Custom Fan Curves
2+
3+
Custom presets are modeled by `CustomFanPreset` and edited through `FanCurveEditorView.swift`. A preset includes a sensor source, curve points, optional update interval, smoothing step, RPM bounds, per-fan offsets, and optional power boost.
4+
5+
The editor constrains point movement, temperature range, speed range, nearest-handle selection, template application, and validation. Tests under `CustomFanPresetTests` and related curve editor geometry coverage protect these rules.
6+
7+
Custom curves are high-risk because they turn user configuration into hardware behavior. Validate bad JSON, invalid curve order, impossible RPM ranges, and fallback defaults defensively.

‎docs/wiki/Dashboard-Architecture.md‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
# Dashboard Architecture
2+
3+
The dashboard is mainly in `ContentView.swift`, `MonitoringDashboardViews.swift`, `FanCurveEditorView.swift`, `FanModeGuidanceCard.swift`, `MenuBarConfigurationSection.swift`, `LaunchAtLoginSection.swift`, `PrivacyControlsSection.swift`, `WeatherLocationAccessSection.swift`, `HelpView.swift`, and support cards such as helper diagnostics.
4+
5+
`ContentView.swift` remains oversized and mixes shell, sidebar, overview cards, system pages, fan controls, Touch Bar customization, helper support, and about surfaces. The architecture docs already call it a pressure point. New UI work should prefer extracting small dedicated views rather than growing it.
6+
7+
Dashboard data should come from `SystemMonitorSnapshot`, `FanController`, `SMCHelperManager`, and settings objects. Avoid ad hoc timers or local telemetry state in SwiftUI views. Detailed process panels should request detailed sampling while visible and release that reason when hidden.
8+
9+
`DashboardWindowLayout.swift` owns safe window sizing and frame reset rules; use it instead of hardcoding dashboard geometry.

‎docs/wiki/Developer-Workflow.md‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
# Developer Workflow
2+
3+
Before editing, read `docs/ARCHITECTURE.md`, relevant feature files, and nearby tests. Prefer the smallest owner of behavior, add focused tests, build, run relevant tests, and inspect user-visible UI directly.
4+
5+
Do not hide broad refactors inside high-risk files. If a change crosses monitoring, helper, fan control, and UI boundaries, document the reason in the commit message and worklog.
6+
7+
Standard test command: `xcodebuild -project Core-Monitor.xcodeproj -scheme Core-Monitor -destination 'platform=macOS' CODE_SIGNING_ALLOWED=NO test`.

‎docs/wiki/Fan-Control.md‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
# Fan Control
2+
3+
`FanController.swift` owns fan modes: Smart, System/Silent, Balanced, Performance, Max, Manual, Custom, and Automatic/System restoration.
4+
5+
Managed modes require the helper because they write fan targets. Monitoring itself does not. Smart mode blends the hottest CPU/GPU reading with system power draw. Balanced and Performance pin fans near fixed percentages of maximum. Manual writes a fixed RPM. Custom follows a persisted curve.
6+
7+
The UI should always explain who owns the fan curve: macOS firmware or Core-Monitor. If Core-Monitor owns it, quitting or switching to automatic should hand control back to the system best-effort.
8+
9+
Fan behavior can lag visibly on Apple Silicon. The guide copy intentionally warns users that a write can succeed before RPM changes are immediately obvious.

0 commit comments

Comments
 (0)