# dreymonde/nicenotifications architecture

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

- Interactive diagram: https://gitdiagram.com/dreymonde/nicenotifications
- Repository: https://github.com/dreymonde/nicenotifications

## Overview

##### Project Type and Purpose
- This is an open-source Swift Package (library) named **NiceNotifications** that reimagines local notifications on Apple platforms.
- It provides a declarative API for scheduling, grouping, permission‐handling, and “timelines” of local notifications.
- Consumers integrate this package into their iOS, watchOS, tvOS, or macOS app via Swift Package Manager.

##### File Structure Analysis
Top-level artifacts:
- Package.swift / Package.resolved – SwiftPM manifest and lock file.
- Sources/NiceNotifications – the library’s implementation.
– NiceNotifications.swift: main façade (`LocalNotifications`).
– NotificationPermissionView.swift: UI component for group-level permission.
- Tests/NiceNotificationsTests – unit tests for the library.
- Xcode workspace files under .swiftpm/xcode – project-level configuration.

##### README Insights
- Describes core concepts: scheduling APIs, permission strategies (system vs group-level), “Notification Timelines,” and advanced guides.
- Mentions dependencies (Apple’s UserNotifications framework and an external DateBuilder library).

##### Main Components
a. Consumer App (host app)
b. NiceNotifications Library
- Facade / API Layer: `LocalNotifications` static methods
- Trigger Definition: DateBuilder types (e.g., `EveryDay`, `NextWeek`)
- Timeline Builder: `NotificationsTimeline` and `LocalNotificationsGroup` protocol
- Permission Layer:
– SystemLevel (`UNUserNotificationCenter`)
– GroupLevel (`NotificationsPermissionView` + in-code strategies)
c. Apple’s UserNotifications Framework (UNUserNotificationCenter)
d. (Optional) DateBuilder External Module
e. Storage: persisting group-level permissions (e.g., UserDefaults)

##### Relationships & Data Flow
1. Consumer App calls `LocalNotifications.schedule(...)` or `reschedule(group:…)`.
2. The DateBuilder trigger objects build next fire dates.
3. `NotificationsTimeline` prepares a sequence of `UNNotificationRequest`s.
4. Permission strategies execute:
– Group-level check (UI or bypass)
– System-level check (ask or validate via `UNUserNotificationCenter.getNotificationSettings`)
5. On approval, library calls `UNUserNotificationCenter.add(request)`.
6. For groups, `LocalNotificationsGroup.getTimeline` may be invoked periodically.
7. UI component (`NotificationPermissionView`) reads/writes group permission state and shows toggles.

##### Architectural Patterns & Principles
- Facade pattern: `LocalNotifications` simplifies complex interactions.
- Builder pattern: DateBuilder helps declare triggers (`Tomorrow().at(...)`).
- Strategy pattern: PermissionStrategy composes group vs system strategies.
- Protocol-oriented design: `LocalNotificationsGroup`, `PermissionAsker`.
- Separation of concerns: UI (permission view) separated from core scheduling logic.

##### Essential Elements
- Clear labels: module names and key classes/protocols.
- Notes on strategies: show strategy selection branch between group vs system.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Consumer App
    subgraph "Consumer App"
        App["Host App"]:::external
    end

    %% NiceNotifications Module
    subgraph "NiceNotifications Module"
        direction TB
        LocalNotifications["LocalNotifications\n(Facade)"]:::publicAPI
        DateBuilder["DateBuilder\n(External)"]:::external
        subgraph "Timeline Builder"
            NotificationsTimeline["NotificationsTimeline"]:::internal
            LocalNotificationsGroup["LocalNotificationsGroup\n(protocol)"]:::internal
        end
        subgraph "Permission Layer"
            NotificationPermissionView["NotificationPermissionView\n(UI Component)"]:::ui
            SystemLevel["SystemLevel\n(Strategy)"]:::internal
        end
        Storage["UserDefaults\n(Storage)"]:::storage
    end

    %% External Frameworks
    UserNotifications["UNUserNotificationCenter\n(Apple Framework)"]:::external

    %% Connections
    App -->|"calls schedule/reschedule()"| LocalNotifications
    LocalNotifications -->|"uses triggers"| DateBuilder
    LocalNotifications -->|"builds timeline"| NotificationsTimeline
    LocalNotifications -->|"invokes group hook"| LocalNotificationsGroup
    NotificationsTimeline -->|"creates UNNotificationRequests"| UserNotifications
    LocalNotifications -->|"permission check"| NotificationPermissionView
    NotificationPermissionView -->|"persist group state"| Storage
    NotificationPermissionView -->|"asks system"| SystemLevel
    SystemLevel -->|"calls getNotificationSettings() / add(request)"| UserNotifications

    %% Click events
    click LocalNotifications "https://github.com/dreymonde/nicenotifications/blob/main/Sources/NiceNotifications/NiceNotifications.swift"
    click NotificationPermissionView "https://github.com/dreymonde/nicenotifications/blob/main/Sources/NiceNotifications/NotificationPermissionView.swift"
    click PackageManifest "https://github.com/dreymonde/nicenotifications/blob/main/Package.swift"
    click PackageResolved "https://github.com/dreymonde/nicenotifications/blob/main/Package.resolved"
    click Tests "https://github.com/dreymonde/nicenotifications/blob/main/Tests/NiceNotificationsTests/NiceNotificationsTests.swift"
    click LinuxMain "https://github.com/dreymonde/nicenotifications/blob/main/Tests/LinuxMain.swift"
    click XCTestManifests "https://github.com/dreymonde/nicenotifications/blob/main/Tests/NiceNotificationsTests/XCTestManifests.swift"
    click XcodeWorkspace "https://github.com/dreymonde/nicenotifications/blob/main/.swiftpm/xcode/package.xcworkspace"
    click MediaAssets "https://github.com/dreymonde/nicenotifications/tree/main/_Media"

    %% Legend (invisible nodes for click targets)
    PackageManifest["Package Manifest"]:::external
    PackageResolved["Resolved Lockfile"]:::external
    Tests["Unit Tests"]:::external
    LinuxMain["LinuxMain"]:::external
    XCTestManifests["XCTest Manifests"]:::external
    XcodeWorkspace["Xcode Workspace Config"]:::external
    MediaAssets["Media Assets"]:::external

    %% Styles
    classDef publicAPI fill:#f9f,stroke:#333,stroke-width:1px
    classDef internal fill:#bbf,stroke:#333,stroke-width:1px
    classDef external fill:#afa,stroke:#333,stroke-width:1px
    classDef ui fill:#fbf,stroke:#333,stroke-width:1px
    classDef storage fill:#ffb,stroke:#333,stroke-width:1px
```
