# demianturner/pollutionmonitor-mac architecture

> Architecture diagram of the GitHub repository demianturner/pollutionmonitor-mac, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-15). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/demianturner/pollutionmonitor-mac
- Repository: https://github.com/demianturner/pollutionmonitor-mac

## Overview

##### 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).

## Diagram (Mermaid)

```mermaid
graph TB
    subgraph "Application Bundle"
        direction TB
        ME["main.m\n(Application bootstrap)"]:::script
        AD["AppDelegate\n(Controller)"]:::ui
        SB["NSStatusItem\n(Status Bar UI)"]:::ui
        PS["PollutionService\n(Network Layer)"]:::network
        AQ[(AQICN API)]:::network
        PM["PLMCityList\n(Model)"]:::model
        SH["NSString+Sha1\n(Utility Extension)"]:::model
        PV["PopoverViewController\n(View)"]:::ui

        ME -->|"launch"| AD
        AD -->|"create"| SB
        AD -->|"schedule fetch"| PS
        PS -->|"HTTP GET"| AQ
        AQ -->|"JSON response"| PS
        PS -->|"parse JSON"| PM
        SH --> PM
        PM -->|"model update"| AD
        AD -->|"update icon/menu"| SB
        SB -->|"user click"| PV
        PV -->|"read data"| PM
    end

    subgraph "Resources & Configuration"
        direction TB
        AK["Api-key.h"]:::resources
        AC["AppIcon Assets"]:::resources
        CEN["cities.plist (en.lproj)"]:::resources
        CZH["cities.plist (zh-Hans.lproj)"]:::resources
        LEN["Localizable.strings (en.lproj)"]:::resources
        LZH["Localizable.strings (zh-Hans.lproj)"]:::resources
        IP["Info.plist\nBundle Settings"]:::resources
        ENT["entitlements"]:::resources
    end

    subgraph "Build & Test"
        direction TB
        SBScript["set_build_number.sh"]:::script
        TEST["PollutionMonitorTests.m"]:::script
    end

    %% Click Events
    click AD "https://github.com/demianturner/pollutionmonitor-mac/blob/master/PollutionMonitor/AppDelegate.h"
    click ME "https://github.com/demianturner/pollutionmonitor-mac/blob/master/PollutionMonitor/main.m"
    click PV "https://github.com/demianturner/pollutionmonitor-mac/blob/master/PollutionMonitor/PopoverViewController.h"
    click AK "https://github.com/demianturner/pollutionmonitor-mac/blob/master/PollutionMonitor/Resources/Api-key.h"
    click PM "https://github.com/demianturner/pollutionmonitor-mac/blob/master/PollutionMonitor/Model/PLMCityList.h"
    click SH "https://github.com/demianturner/pollutionmonitor-mac/blob/master/PollutionMonitor/NSString+Sha1.h"
    click AC "https://github.com/demianturner/pollutionmonitor-mac/blob/master/PollutionMonitor/Assets.xcassets/AppIcon.appiconset/Contents.json"
    click CEN "https://github.com/demianturner/pollutionmonitor-mac/blob/master/PollutionMonitor/en.lproj/cities.plist"
    click CZH "https://github.com/demianturner/pollutionmonitor-mac/blob/master/PollutionMonitor/zh-Hans.lproj/cities.plist"
    click LEN "https://github.com/demianturner/pollutionmonitor-mac/blob/master/PollutionMonitor/Resources/en.lproj/Localizable.strings"
    click LZH "https://github.com/demianturner/pollutionmonitor-mac/blob/master/PollutionMonitor/Resources/zh-Hans.lproj/Localizable.strings"
    click SBScript "https://github.com/demianturner/pollutionmonitor-mac/blob/master/PollutionMonitor/Scripts/set_build_number.sh"
    click IP "https://github.com/demianturner/pollutionmonitor-mac/blob/master/PollutionMonitor/Info.plist"
    click ENT "https://github.com/demianturner/pollutionmonitor-mac/blob/master/PollutionMonitor/PollutionMonitor.entitlements"
    click TEST "https://github.com/demianturner/pollutionmonitor-mac/blob/master/PollutionMonitorTests/PollutionMonitorTests.m"
    click XCODE1 "https://github.com/demianturner/pollutionmonitor-mac/blob/master/PollutionMonitor.xcodeproj/project.pbxproj"
    click XCODE2 "https://github.com/demianturner/pollutionmonitor-mac/blob/master/PollutionMonitor.xcworkspace/contents.xcworkspacedata"

    classDef ui fill:#CEF6FF,stroke:#0066CC,stroke-width:1px
    classDef model fill:#E0FFD8,stroke:#009900,stroke-width:1px
    classDef network fill:#FFE4B5,stroke:#CC6600,stroke-width:1px
    classDef resources fill:#F2F2F2,stroke:#666666,stroke-width:1px
    classDef script fill:#F2F2F2,stroke:#666666,stroke-width:1px
```
