MeetingBar Documentation

The codebase is organized into functional modules:

• App/: Process lifecycle, OS integration, AppModel, AppIntent (Shortcuts), and URLHandler.
• Calendar/: Calendar data models (MBEvent, MBCalendar), filtering, and providers (EventKit, Google). CalendarSync manages the refresh pipeline.
• Meetings/: Meeting URL detection and opening logic (MeetingOpener, MeetingLinkDetector).
• Notifications/: Scheduling and reconciling UNNotification requests (NotificationScheduler, NotificationActionRunner).
• Settings/: Persistent settings via AppSettings.
• UI/:
  • StatusBar/: Menu bar item and menu construction.
  • Views/: SwiftUI views (e.g., DayTimelineView, FullscreenNotification).
• Utilities/: Logging, Keychain, and AppleScript runners.

All persistent settings are managed via the Defaults library and defined in Extensions/DefaultsKeys.swift.

The Rule: Read Defaults only at boundaries (in adapters), never deep inside pure policies. This ensures policies remain hostless-testable.

To add a setting to a policy, create a settings struct and a static var current factory in the adapter file that snapshots the required Defaults values.

extension StatusBarPresentationSettings {
    static var current: StatusBarPresentationSettings {
        StatusBarPresentationSettings(
            hasSelectedCalendars: !Defaults[.selectedCalendarIDs].isEmpty,
            showEventMaxTimeUntilEventEnabled: Defaults[.showEventMaxTimeUntilEventEnabled],
            showEventMaxTimeUntilEventThreshold: Defaults[.showEventMaxTimeUntilEventThreshold]
        )
    }
}

MeetingBar supports two primary calendar sources. After installation, follow the onboarding process to select your preferred provider:

• macOS Calendar: Uses any account synchronized with Calendar.app (e.g., iCloud, Google, Exchange, Office 365, Yahoo, AOL).
• Google Calendar: Connects directly to Google Calendar via OAuth.

MeetingBar requires macOS 12.0 or later. You can install it using one of the following methods:

• Mac App Store: Download directly from the Mac App Store.
• Homebrew: Use the --cask flag to install.
• Manual download: Download the latest .dmg file from the GitHub releases page.

brew install --cask meetingbar

To add a new calendar provider (e.g., Microsoft Graph), implement the EventStore protocol. You must map the provider's specific events into the MBEvent type and expose calendars as MBCalendar.

Crucial Rule: Do not allow provider-specific types to leak past the EventStore boundary. The rest of the application must interact only with provider-agnostic types to maintain architecture integrity.

Use the following make commands to manage the development lifecycle:

| Command | Description | |---|---|<br>|---|---|make build | Debug build | | make build-quiet | Debug build with filtered output | | make build-release | Release build | | make test | Full suite with coverage (host + logic) | | make test-quiet | Full suite with filtered output | | make test-logic | Hostless logic tests only (fast) | | make test-logic-quiet | Hostless logic tests with filtered output | | make lint | Run SwiftLint | | make validate-strings | Verify every .loco() key exists in en.lproj/Localizable.strings | | make open | Open the project in Xcode |

MeetingBar distinguishes between tests that require the full app environment and those that run against pure logic.

Best Practice: Default to hostless tests. If a test requires launching the app, it is a signal that you are testing a service rather than a pure policy.

When adding new features, follow this target shape to maintain simplicity:

1. UI sends actions.
2. AppModel coordinates.
3. Feature components own workflows.
4. Policies decide.
5. macOS integrations execute side effects.

Guidelines:

• Use existing MeetingBar naming conventions (e.g., CalendarSync, MeetingOpener, NotificationScheduler, AppSettings, WindowCoordinator) instead of generic architectural labels.
• A new type should only be created if it provides a workflow a clear owner or makes a decision testable.

MeetingBar uses a reconciliation model for notifications rather than scheduling them directly upon every event change.

1. Planning: NotificationPlanner.plan takes events and settings to produce a [NotificationPlan] containing specific kinds like .eventStart or .eventEnd.
2. Reconciliation: NotificationScheduler.reconcile compares the desired plan against the actual pending requests in UNUserNotificationCenter.
3. Identifiers: Notifications use stable identifiers following the pattern mb-plan-<eventID>-<kind>. This makes the reconciliation process idempotent; calling it multiple times with the same state results in no changes.
4. Actions: NotificationActionRunner handles in-app actions (fullscreen, auto-join, etc.). It uses a NotificationRecordStore to ensure actions are not re-fired during subsequent reconciliations.