# w77sh/maa architecture

> Architecture diagram of the GitHub repository w77sh/maa, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/w77sh/maa
- Repository: https://github.com/w77sh/maa

## Overview

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: [`Drink Reminder/Reminder/ReminderManager.swift`](https://github.com/w77sh/maa/blob/HEAD/Drink%20Reminder/Reminder/ReminderManager.swift) (Reminder manager), [`Drink Reminder/App/Drink_ReminderApp.swift`](https://github.com/w77sh/maa/blob/HEAD/Drink%20Reminder/App/Drink_ReminderApp.swift) (App entry), [`Drink Reminder/MenuBar/MenuBarView.swift`](https://github.com/w77sh/maa/blob/HEAD/Drink%20Reminder/MenuBar/MenuBarView.swift) (Menu bar), [`Drink Reminder/Utils/Localizer.swift`](https://github.com/w77sh/maa/blob/HEAD/Drink%20Reminder/Utils/Localizer.swift) (Localizer)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["UI"]
  node_app_entry["App entry<br/>SwiftUI app"]
  node_menu_bar_ui["Menu bar<br/>Popover UI<br/>[MenuBarView.swift]"]
  node_settings_ui["Settings<br/>Config UI<br/>[SettingsView.swift]"]
  node_onboarding_ui["Onboarding<br/>First-run UI"]
  node_stats_ui["Statistics<br/>Progress UI"]
end

subgraph group_domain["Domain/State"]
  node_app_settings["Settings model<br/>Domain model<br/>[AppSettings.swift]"]
  node_reminder_state["Reminder state<br/>Runtime model"]
  node_history_store[("History store<br/>Daily history")]
  node_state_store[("State store<br/>State persistence")]
  node_settings_store[("Settings store<br/>Config bridge")]
end

subgraph group_services["Reminder/Notification Services"]
  node_scheduler{{"Scheduler<br/>Timing engine"}}
  node_manager["Reminder manager<br/>Orchestrator"]
  node_notifier["Notifications"]
end

subgraph group_platform["Platform/Distribution"]
  node_localizer["Localizer<br/>i18n helper<br/>[Localizer.swift]"]
  node_time_utils["Time utils<br/>Date helpers<br/>[TimeUtils.swift]"]
  node_assets[("Assets<br/>[Assets.xcassets]")]
  node_locales_en["English strings<br/>Localization"]
  node_locales_ar["Arabic strings<br/>Localization"]
  node_info_plist["Info plist<br/>App metadata<br/>[Info.plist]"]
  node_release_workflow["Release workflow<br/>CI/CD<br/>[release.yml]"]
  node_scripts["Release scripts<br/>Automation<br/>[build-release.sh]"]
end

node_app_entry -->|"hosts"| node_menu_bar_ui
node_app_entry -->|"opens"| node_settings_ui
node_app_entry -->|"shows"| node_onboarding_ui
node_app_entry -->|"navigates"| node_stats_ui
node_menu_bar_ui -->|"acts through"| node_manager
node_settings_ui -->|"edits"| node_settings_store
node_settings_store -->|"persists"| node_app_settings
node_manager -->|"uses"| node_scheduler
node_manager -->|"alerts via"| node_notifier
node_manager -->|"updates"| node_reminder_state
node_manager -->|"stores"| node_state_store
node_manager -->|"reads"| node_settings_store
node_manager -->|"logs"| node_history_store
node_history_store -->|"feeds"| node_stats_ui
node_state_store -->|"reflects"| node_menu_bar_ui
node_scheduler -->|"calculates with"| node_time_utils
node_stats_ui -->|"formats with"| node_time_utils
node_settings_ui -->|"renders with"| node_localizer
node_menu_bar_ui -->|"renders with"| node_localizer
node_app_entry -->|"uses"| node_assets
node_app_entry -->|"configured by"| node_info_plist
node_localizer -->|"loads"| node_locales_en
node_localizer -->|"loads"| node_locales_ar
node_release_workflow -->|"drives"| node_scripts

click node_app_entry "https://github.com/w77sh/maa/blob/main/Drink Reminder/App/Drink_ReminderApp.swift"
click node_menu_bar_ui "https://github.com/w77sh/maa/blob/main/Drink Reminder/MenuBar/MenuBarView.swift"
click node_settings_ui "https://github.com/w77sh/maa/blob/main/Drink Reminder/Settings/SettingsView.swift"
click node_onboarding_ui "https://github.com/w77sh/maa/blob/main/Drink Reminder/UI/OnboardingView.swift"
click node_stats_ui "https://github.com/w77sh/maa/blob/main/Drink Reminder/UI/StatisticsView.swift"
click node_app_settings "https://github.com/w77sh/maa/blob/main/Drink Reminder/Model/AppSettings.swift"
click node_reminder_state "https://github.com/w77sh/maa/blob/main/Drink Reminder/Model/ReminderState.swift"
click node_history_store "https://github.com/w77sh/maa/blob/main/Drink Reminder/Model/DailyHistoryStore.swift"
click node_state_store "https://github.com/w77sh/maa/blob/main/Drink Reminder/Model/ReminderStateStore.swift"
click node_settings_store "https://github.com/w77sh/maa/blob/main/Drink Reminder/Settings/SettingsStore.swift"
click node_scheduler "https://github.com/w77sh/maa/blob/main/Drink Reminder/Reminder/ReminderScheduler.swift"
click node_manager "https://github.com/w77sh/maa/blob/main/Drink Reminder/Reminder/ReminderManager.swift"
click node_notifier "https://github.com/w77sh/maa/blob/main/Drink Reminder/Notification/NotificationManager.swift"
click node_localizer "https://github.com/w77sh/maa/blob/main/Drink Reminder/Utils/Localizer.swift"
click node_time_utils "https://github.com/w77sh/maa/blob/main/Drink Reminder/Utils/TimeUtils.swift"
click node_assets "https://github.com/w77sh/maa/blob/main/Drink Reminder/Assets.xcassets"
click node_locales_en "https://github.com/w77sh/maa/blob/main/Drink Reminder/en.lproj/Localizable.strings"
click node_locales_ar "https://github.com/w77sh/maa/blob/main/Drink Reminder/ar.lproj/Localizable.strings"
click node_info_plist "https://github.com/w77sh/maa/blob/main/Drink Reminder/Info.plist"
click node_release_workflow "https://github.com/w77sh/maa/blob/main/.github/workflows/release.yml"
click node_scripts "https://github.com/w77sh/maa/blob/main/scripts/build-release.sh"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_app_entry,node_menu_bar_ui,node_settings_ui,node_onboarding_ui,node_stats_ui toneBlue
class node_app_settings,node_reminder_state,node_history_store,node_state_store,node_settings_store toneAmber
class node_scheduler,node_manager,node_notifier toneMint
class node_localizer,node_time_utils,node_assets,node_locales_en,node_locales_ar,node_info_plist,node_release_workflow,node_scripts toneRose
```

## Components

### UI

SwiftUI surfaces for the status bar app, onboarding, statistics, and settings.

- [App entry](https://github.com/w77sh/maa/blob/HEAD/Drink%20Reminder/App/Drink_ReminderApp.swift): SwiftUI app · Application lifecycle and top-level composition. · `Drink Reminder/App/Drink_ReminderApp.swift`
- [Menu bar](https://github.com/w77sh/maa/blob/HEAD/Drink%20Reminder/MenuBar/MenuBarView.swift): Popover UI · Status bar popover for reminder state, logging, and goal feedback. · `Drink Reminder/MenuBar/MenuBarView.swift`
- [Settings](https://github.com/w77sh/maa/blob/HEAD/Drink%20Reminder/Settings/SettingsView.swift): Config UI · Preferences surface for reminders, goals, and app options. · `Drink Reminder/Settings/SettingsView.swift`
- [Onboarding](https://github.com/w77sh/maa/blob/HEAD/Drink%20Reminder/UI/OnboardingView.swift): First-run UI · Introductory guidance shown on initial launch. · `Drink Reminder/UI/OnboardingView.swift`
- [Statistics](https://github.com/w77sh/maa/blob/HEAD/Drink%20Reminder/UI/StatisticsView.swift): Progress UI · Hydration history and progress presentation. · `Drink Reminder/UI/StatisticsView.swift`

### Domain/State

App settings, reminder state, and hydration history persistence.

- [Settings model](https://github.com/w77sh/maa/blob/HEAD/Drink%20Reminder/Model/AppSettings.swift): Domain model · User-configurable app preferences and hydration goals. · `Drink Reminder/Model/AppSettings.swift`
- [Reminder state](https://github.com/w77sh/maa/blob/HEAD/Drink%20Reminder/Model/ReminderState.swift): Runtime model · Current reminder status across the app session. · `Drink Reminder/Model/ReminderState.swift`
- [History store](https://github.com/w77sh/maa/blob/HEAD/Drink%20Reminder/Model/DailyHistoryStore.swift): Daily history · Persistent daily intake records used for stats and progress. · `Drink Reminder/Model/DailyHistoryStore.swift`
- [State store](https://github.com/w77sh/maa/blob/HEAD/Drink%20Reminder/Model/ReminderStateStore.swift): State persistence · Persists and restores reminder-related runtime state. · `Drink Reminder/Model/ReminderStateStore.swift`
- [Settings store](https://github.com/w77sh/maa/blob/HEAD/Drink%20Reminder/Settings/SettingsStore.swift): Config bridge · Bridges settings UI and persisted configuration. · `Drink Reminder/Settings/SettingsStore.swift`

### Reminder/Notification Services

Scheduling, orchestration, and macOS notification delivery.

- [Scheduler](https://github.com/w77sh/maa/blob/HEAD/Drink%20Reminder/Reminder/ReminderScheduler.swift): Timing engine · Computes when reminders should fire. · `Drink Reminder/Reminder/ReminderScheduler.swift`
- [Reminder manager](https://github.com/w77sh/maa/blob/HEAD/Drink%20Reminder/Reminder/ReminderManager.swift): Orchestrator · Coordinates scheduling, state transitions, and user actions. · `Drink Reminder/Reminder/ReminderManager.swift`
- [Notifications](https://github.com/w77sh/maa/blob/HEAD/Drink%20Reminder/Notification/NotificationManager.swift): macOS notifications · System notification delivery boundary. · `Drink Reminder/Notification/NotificationManager.swift`

### Platform/Distribution

macOS resources, localization, app metadata, release automation, and scripts.

- [Localizer](https://github.com/w77sh/maa/blob/HEAD/Drink%20Reminder/Utils/Localizer.swift): i18n helper · Text lookup and language handling for multilingual UI. · `Drink Reminder/Utils/Localizer.swift`
- [Time utils](https://github.com/w77sh/maa/blob/HEAD/Drink%20Reminder/Utils/TimeUtils.swift): Date helpers · Shared date and time calculations for reminders and stats. · `Drink Reminder/Utils/TimeUtils.swift`
- [Assets](https://github.com/w77sh/maa/blob/HEAD/Drink%20Reminder/Assets.xcassets): XCAssets · App icon and status bar artwork for normal and paused states. · `Drink Reminder/Assets.xcassets`
- [English strings](https://github.com/w77sh/maa/blob/HEAD/Drink%20Reminder/en.lproj/Localizable.strings): Localization · English localized resources. · `Drink Reminder/en.lproj/Localizable.strings`
- [Arabic strings](https://github.com/w77sh/maa/blob/HEAD/Drink%20Reminder/ar.lproj/Localizable.strings): Localization · Arabic localized resources with RTL considerations. · `Drink Reminder/ar.lproj/Localizable.strings`
- [Info plist](https://github.com/w77sh/maa/blob/HEAD/Drink%20Reminder/Info.plist): App metadata · macOS app metadata and behavior settings. · `Drink Reminder/Info.plist`
- [Release workflow](https://github.com/w77sh/maa/blob/main/.github/workflows/release.yml): CI/CD · GitHub Actions release automation. · `.github/workflows/release.yml`
- [Release scripts](https://github.com/w77sh/maa/blob/main/scripts/build-release.sh): Automation · Packaging, tagging, and local install helpers. · `scripts/build-release.sh`

## Connections

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