How w77sh/maa works
1. Project shape
- This is a native macOS menu bar app built in Swift 5.9+ with SwiftUI and AppKit integration where needed.
- The app’s center of gravity is a lightweight hydration reminder that lives in the status bar, with a popover UI and a separate settings window.
2. App entry and shell
- Drink Reminder/App/Drink_ReminderApp.swift is the application entry point.
- It wires together the app lifecycle, top-level state, and the main UI surfaces rather than using a traditional multi-window document architecture.
3. Primary UI surfaces
- MenuBar/MenuBarView.swift is the core status-bar popover experience: it shows current reminder state, drink logging, and the “goal reached” feedback.
- Settings/SettingsView.swift is the configuration surface for reminder intervals, daily goals, and related preferences.
- UI/OnboardingView.swift handles first-run guidance, while UI/StatisticsView.swift presents hydration progress/history.
4. State and persistence layer
- Model/AppSettings.swift defines the user-configurable settings domain.
- Model/ReminderState.swift represents the current runtime reminder state.
- Model/DailyHistoryStore.swift tracks logged intake over time for daily progress and statistics.
- Model/ReminderStateStore.swift persists or restores reminder-related state across launches.
5. Settings flow
- The user edits settings in the UI.
- Settings/SettingsStore.swift acts as the bridge between the settings UI and persisted app configuration.
- Those settings feed the reminder engine and also influence UI behavior, such as the current schedule and the displayed status.
6. Reminder engine
- Reminder/ReminderScheduler.swift is the timing subsystem that decides when reminders should fire.
- Reminder/ReminderManager.swift coordinates scheduling, state transitions, and user actions like logging a drink or pausing reminders.
- This is the main business-logic boundary: UI talks to manager/store objects, and the manager talks to scheduling and notification services.
7. Notification delivery
- Notification/NotificationManager.swift is the system notification boundary.
- It isolates macOS notification delivery from the reminder logic so the scheduler/manager can remain focused on hydration rules rather than platform APIs.
8. Data and control flow
- Typical flow is: user configures settings → settings are stored → scheduler computes reminder times → manager updates reminder state → notification manager delivers alerts → UI reflects current state and logs intake.
- Daily history and reminder state are the two main persistent streams: one for long-term stats, one for runtime reminder behavior.
9. Localization and time utilities
- Utils/Localizer.swift centralizes text lookup and language handling.
- Utils/TimeUtils.swift contains shared date/time formatting or calculation helpers used by reminder scheduling, stats, and UI presentation.
- Localization resources live under en.lproj and ar.lproj, so the app is explicitly multi-language and includes right-to-left support considerations.
10. Assets and platform resources
- Assets.xcassets contains the app icon plus status bar icons, including separate artwork for normal and paused states.
- Info.plist and the Xcode project define the macOS app metadata, menu bar behavior, and build configuration.
11. Tests
- Drink ReminderTests/ReminderManagerTests.swift, ReminderSchedulerTests.swift, and SettingsStoreTests.swift cover the most important logic boundaries.
- The test suite is concentrated around scheduling correctness, reminder behavior, and settings persistence rather than UI snapshot testing.
12. Release and distribution
- .github/workflows/release.yml and the scripts/ directory show a release pipeline oriented around packaging, tagging, and local installation.
- scripts/build-release.sh, scripts/release-next-tag.sh, and scripts/install-local-app.sh support building and shipping a macOS app bundle/DMG flow, consistent with the README’s Homebrew Cask and direct-download distribution story.
13. Architecture summary for a diagram
- Draw four main zones: UI, domain/state, reminder/notification services, and platform/distribution.
- The UI is SwiftUI-driven; the domain layer owns settings, reminder state, and history; the services layer owns scheduling and notifications; and the platform layer is macOS-specific resources, assets, localization, and release automation.
Main entry points: ReminderManager.swift Reminder manager · Drink_ReminderApp.swift App entry · MenuBarView.swift Menu bar · Localizer.swift Localizer
Components 21
UI
SwiftUI surfaces for the status bar app, onboarding, statistics, and settings.
- App entry · Application lifecycle and top-level composition.
Drink Reminder/App/Drink_ReminderApp.swift - Menu bar · Status bar popover for reminder state, logging, and goal feedback.
Drink Reminder/MenuBar/MenuBarView.swift - Settings · Preferences surface for reminders, goals, and app options.
Drink Reminder/Settings/SettingsView.swift - Onboarding · Introductory guidance shown on initial launch.
Drink Reminder/UI/OnboardingView.swift - Statistics · Hydration history and progress presentation.
Drink Reminder/UI/StatisticsView.swift
Domain/State
App settings, reminder state, and hydration history persistence.
- Settings model · User-configurable app preferences and hydration goals.
Drink Reminder/Model/AppSettings.swift - Reminder state · Current reminder status across the app session.
Drink Reminder/Model/ReminderState.swift - History store · Persistent daily intake records used for stats and progress.
Drink Reminder/Model/DailyHistoryStore.swift - State store · Persists and restores reminder-related runtime state.
Drink Reminder/Model/ReminderStateStore.swift - Settings store · Bridges settings UI and persisted configuration.
Drink Reminder/Settings/SettingsStore.swift
Reminder/Notification Services
Scheduling, orchestration, and macOS notification delivery.
- Scheduler · Computes when reminders should fire.
Drink Reminder/Reminder/ReminderScheduler.swift - Reminder manager · Coordinates scheduling, state transitions, and user actions.
Drink Reminder/Reminder/ReminderManager.swift - Notifications · System notification delivery boundary.
Drink Reminder/Notification/NotificationManager.swift
Platform/Distribution
macOS resources, localization, app metadata, release automation, and scripts.
- Localizer · Text lookup and language handling for multilingual UI.
Drink Reminder/Utils/Localizer.swift - Time utils · Shared date and time calculations for reminders and stats.
Drink Reminder/Utils/TimeUtils.swift - Assets · App icon and status bar artwork for normal and paused states.
Drink Reminder/Assets.xcassets - English strings · English localized resources.
Drink Reminder/en.lproj/Localizable.strings - Arabic strings · Arabic localized resources with RTL considerations.
Drink Reminder/ar.lproj/Localizable.strings - Info plist · macOS app metadata and behavior settings.
Drink Reminder/Info.plist - Release workflow · GitHub Actions release automation.
.github/workflows/release.yml - Release scripts · Packaging, tagging, and local install helpers.
scripts/build-release.sh
Connections 24
- App entry → Menu bar: hosts · The app composes the main status-bar experience.
- App entry → Settings: opens · The app provides the settings surface.
- App entry → Onboarding: shows · First-run guidance is part of the app shell.
- App entry → Statistics: navigates · The app exposes progress and history views.
- Menu bar → Reminder manager: acts through · Menu bar actions are handled by the reminder orchestrator.
- Settings → Settings store: edits · Settings UI reads and writes via the settings bridge.
- Settings store → Settings model: persists · The store manages persisted configuration.
- Reminder manager → Scheduler: uses · Reminder logic delegates timing decisions to the scheduler.
- Reminder manager → Notifications: alerts via · Notifications are delivered through the platform boundary.
- Reminder manager → Reminder state: updates · The orchestrator mutates runtime reminder state.
- Reminder manager → State store: stores · Reminder state is persisted across launches.
- Reminder manager → Settings store: reads · Scheduling and behavior depend on configured settings.
- Reminder manager → History store: logs · Drink actions are recorded for daily progress and stats.
- History store → Statistics: feeds · History data powers the statistics screen.
- State store → Menu bar: reflects · Persisted runtime state drives the current popover status.
- Scheduler → Time utils: calculates with · Shared date/time helpers support reminder timing.
- Statistics → Time utils: formats with · Statistics uses shared date/time presentation helpers.
- Settings → Localizer: renders with · UI text is localized through the shared helper.
- Menu bar → Localizer: renders with · Status bar UI uses localized strings.
- App entry → Assets: uses · The app loads icons and status bar artwork.
- App entry → Info plist: configured by · App metadata and platform behavior are defined here.
- Localizer → English strings: loads · English translation resources are bundled with the app.
- Localizer → Arabic strings: loads · Arabic translation resources are bundled with the app.
- Release workflow → Release scripts: drives · CI release automation relies on repository scripts.