How demianturner/pollutionmonitor-mac works
Project Type and Purpose
• PollutionMonitor-Mac is a native macOS status-bar application (Objective-C/Cocoa) that periodically fetches AQI data from the AQICN API and renders it in the menu bar and a popover.
• It is structured as a single-bundle Mac app (no separate frontend/backend servers), using MVC patterns inside the Cocoa framework.
File Structure
• Top-level Xcode files and workspace: “PollutionMonitor.xcodeproj” and “Podfile” indicate use of Xcode and possibly CocoaPods.
• “PollutionMonitor/” directory: contains source code, resources, scripts, and localization.
– Controllers: AppDelegate.[h,m], PopoverViewController.[h,m], and corresponding XIBs.
– Model: PLMCityList.[h,m] for city/PLM data.
– Extensions: NSString+Sha1.[h,m] for hashing (likely for token/security).
– Resources: Api-key.h, asset catalogs (AppIcon), localized strings, cities.plist data files.
– Scripts: set_build_number.sh (build-time version management).
• Test target: PollutionMonitorTests shows a unit-test harness for core logic.
Extract Architecture from README
• Fetches minimal JSON payload (~105 bytes) from AQICN web API.
• Uses native Cocoa networking (NSURLSession or similar), image compositing, and menu management.
Main Components and Their Relationships
a. Status Bar UI (NSStatusItem)
b. Network Layer (PollutionService)
– Periodic scheduler (NSTimer or GCD) triggers API calls to AQICN.
– Parses JSON and maps to Model objects (PLMCityList).
c. Data Model (PLMCityList, NSString+Sha1)
– Holds current AQI data, city list, and handles any hashing/signature for requests.
d. Popover UI (PopoverViewController + XIB)
– Displays detailed pollution readings and options when the user clicks the status item.
e. Resources & Configuration
– Localization bundles (en.lproj, zh-Hans.lproj).
f. Build & Test
– set_build_number.sh updates CFBundleVersion automatically.
– PollutionMonitorTests validates parsing logic and model integrity.
Data Flows and Interactions
1) AppDelegate on launch → creates NSStatusItem and schedules fetch timer
2) Timer fires → Network Layer makes HTTPS request to AQICN using API-key
3) Response arrives → JSON parsed into PLMCityList (Model)
6) On user click → PopoverViewController loads detailed view from XIB, reading from Model
Architectural Patterns & Tech
• MVC: Controllers (AppDelegate, PopoverViewController), Models (PLMCityList), Views (XIBs, NSStatusItem).
• Extension Methods for utility (NSString+Sha1).
• Localization for international support.
• Scripted build tasks (set_build_number.sh) for CI/version control.
• Unit tests for core logic (PollutionMonitorTests).