# hhru/nivelir architecture

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

- Interactive diagram: https://gitdiagram.com/hhru/nivelir
- Repository: https://github.com/hhru/nivelir

## Overview

Nivelir is a Swift navigation DSL for iOS and tvOS. An app defines screens, then submits chainable routes to a navigator, which finds UIKit containers and performs stack, modal, tab, and window navigation. Deep links form a separate input path: the manager resolves URL, notification, or shortcut payloads, applies interceptors, and asks the navigator to navigate. The repository also provides UI addons, including a configurable bottom-sheet presentation system, plus decoding utilities used by deep-link handling. Addon relationships are limited where implementation excerpts were not provided.

Main entry points: [`Sources/Deeplink/DeeplinkManager.swift`](https://github.com/hhru/nivelir/blob/main/Sources/Deeplink/DeeplinkManager.swift) (Deep Link Manager), [`Sources/Screen/Navigator/ScreenNavigator.swift`](https://github.com/hhru/nivelir/blob/main/Sources/Screen/Navigator/ScreenNavigator.swift) (Screen Navigator), [`Sources/Addons/BottomSheet/Presentation/BottomSheetPresentationController.swift`](https://github.com/hhru/nivelir/blob/main/Sources/Addons/BottomSheet/Presentation/BottomSheetPresentationController.swift) (Sheet Presentation), [`Sources/Addons/BottomSheet/BottomSheetController.swift`](https://github.com/hhru/nivelir/blob/main/Sources/Addons/BottomSheet/BottomSheetController.swift) (Sheet Controller)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_navigation["Screen Navigation"]
  node_screen["Screen Definition<br/>[Screen.swift]"]
  node_routes["Route DSL<br/>[ScreenRoute.swift]"]
  node_actions["Navigation Actions<br/>[ScreenAction.swift]"]
  node_navigator["Screen Navigator"]
  node_containers["UIKit Containers"]
  node_observation["Navigation Observation"]
end

subgraph group_deeplinks["Deep Links"]
  node_deeplink_input["Link Inputs<br/>[URLDeeplink.swift]"]
  node_notification_link["Notification Links"]
  node_shortcut_link["Shortcut Links"]
  node_deeplink_manager["Deep Link Manager"]
  node_interceptors["Link Interceptors"]
  node_link_storage["Link Storage"]
end

subgraph group_addons["UI Addons"]
  node_addons_api["Screen Addon Actions"]
  node_media_picker["Media Picker"]
  node_document_preview["Document Preview"]
  node_safari["Safari Launcher"]
  node_sharing["Sharing<br/>[Sharing.swift]"]
  node_hud["Progress HUD<br/>[HUD.swift]"]
end

subgraph group_bottomsheet["Bottom Sheet"]
  node_bottomsheet_api["Bottom Sheet API<br/>[BottomSheet.swift]"]
  node_sheet_controller["Sheet Controller"]
  node_sheet_presentation["Sheet Presentation"]
  node_sheet_detents["Detent Resolver"]
  node_sheet_interaction["Gesture Interaction"]
end

subgraph group_decoding["Decoding Tools"]
  node_url_decoder["URL Query Decoder"]
  node_dictionary_decoder["Dictionary Decoder"]
end

node_app(("App"))

node_app -->|"defines"| node_screen
node_app -->|"builds routes"| node_routes
node_app -->|"submits navigation"| node_navigator
node_navigator -->|"finds containers"| node_containers
node_navigator -.->|"supports observation"| node_observation
node_deeplink_manager -->|"requests navigation"| node_navigator
node_deeplink_manager -->|"runs interceptors"| node_interceptors
node_deeplink_manager -->|"stores resolved link"| node_link_storage
node_deeplink_manager -->|"decodes URL query"| node_url_decoder
node_deeplink_manager -->|"decodes payload"| node_dictionary_decoder
node_media_picker -.->|"implements action"| node_addons_api
node_sheet_controller -->|"creates presentation"| node_sheet_presentation
node_sheet_presentation -->|"resolves detents"| node_sheet_detents
node_sheet_presentation -->|"delegates gestures"| node_sheet_interaction
node_sheet_controller -->|"copies configuration"| node_bottomsheet_api
node_deeplink_input -.->|"is resolved by"| node_deeplink_manager
node_notification_link -.->|"is resolved by"| node_deeplink_manager
node_shortcut_link -.->|"is resolved by"| node_deeplink_manager

click node_screen "https://github.com/hhru/nivelir/blob/main/Sources/Screen/Screen.swift"
click node_routes "https://github.com/hhru/nivelir/blob/main/Sources/Screen/Route/ScreenRoute.swift"
click node_actions "https://github.com/hhru/nivelir/blob/main/Sources/Screen/Actions/ScreenAction.swift"
click node_navigator "https://github.com/hhru/nivelir/blob/main/Sources/Screen/Navigator/ScreenNavigator.swift"
click node_containers "https://github.com/hhru/nivelir/blob/main/Sources/Screen/Container/ScreenContainer.swift"
click node_observation "https://github.com/hhru/nivelir/blob/main/Sources/Screen/Observation/ScreenObserver.swift"
click node_deeplink_input "https://github.com/hhru/nivelir/blob/main/Sources/Deeplink/URL/URLDeeplink.swift"
click node_notification_link "https://github.com/hhru/nivelir/blob/main/Sources/Deeplink/Notification/NotificationDeeplink.swift"
click node_shortcut_link "https://github.com/hhru/nivelir/blob/main/Sources/Deeplink/Shortcut/ShortcutDeeplink.swift"
click node_deeplink_manager "https://github.com/hhru/nivelir/blob/main/Sources/Deeplink/DeeplinkManager.swift"
click node_interceptors "https://github.com/hhru/nivelir/blob/main/Sources/Deeplink/DeeplinkInterceptor.swift"
click node_link_storage "https://github.com/hhru/nivelir/blob/main/Sources/Deeplink/DeeplinkStorage.swift"
click node_addons_api "https://github.com/hhru/nivelir/tree/main/Sources/Addons"
click node_media_picker "https://github.com/hhru/nivelir/blob/main/Sources/Addons/MediaPicker/MediaPickerManager.swift"
click node_document_preview "https://github.com/hhru/nivelir/blob/main/Sources/Addons/DocumentPreview/DocumentPreviewManager.swift"
click node_safari "https://github.com/hhru/nivelir/blob/main/Sources/Addons/Safari/SafariManager.swift"
click node_sharing "https://github.com/hhru/nivelir/blob/main/Sources/Addons/Sharing/Sharing.swift"
click node_hud "https://github.com/hhru/nivelir/blob/main/Sources/Addons/HUD/HUD.swift"
click node_bottomsheet_api "https://github.com/hhru/nivelir/blob/main/Sources/Addons/BottomSheet/BottomSheet.swift"
click node_sheet_controller "https://github.com/hhru/nivelir/blob/main/Sources/Addons/BottomSheet/BottomSheetController.swift"
click node_sheet_presentation "https://github.com/hhru/nivelir/blob/main/Sources/Addons/BottomSheet/Presentation/BottomSheetPresentationController.swift"
click node_sheet_detents "https://github.com/hhru/nivelir/blob/main/Sources/Addons/BottomSheet/Detention/BottomSheetDetentionController.swift"
click node_sheet_interaction "https://github.com/hhru/nivelir/blob/main/Sources/Addons/BottomSheet/Interaction/BottomSheetInteractionController.swift"
click node_url_decoder "https://github.com/hhru/nivelir/blob/main/Sources/Tools/URLQueryDecoder/URLQueryDecoder.swift"
click node_dictionary_decoder "https://github.com/hhru/nivelir/blob/main/Sources/Tools/DictionaryDecoder/DictionaryDecoder.swift"

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_screen,node_routes,node_actions,node_navigator,node_containers,node_observation toneBlue
class node_deeplink_input,node_notification_link,node_shortcut_link,node_deeplink_manager,node_interceptors,node_link_storage toneAmber
class node_addons_api,node_media_picker,node_document_preview,node_safari,node_sharing,node_hud toneMint
class node_bottomsheet_api,node_sheet_controller,node_sheet_presentation,node_sheet_detents,node_sheet_interaction toneRose
class node_url_decoder,node_dictionary_decoder,node_app toneIndigo
```

## Components

### Screen Navigation

- [Screen Definition](https://github.com/hhru/nivelir/blob/main/Sources/Screen/Screen.swift): `Sources/Screen/Screen.swift`
- [Route DSL](https://github.com/hhru/nivelir/blob/main/Sources/Screen/Route/ScreenRoute.swift): `Sources/Screen/Route/ScreenRoute.swift`
- [Navigation Actions](https://github.com/hhru/nivelir/blob/main/Sources/Screen/Actions/ScreenAction.swift): `Sources/Screen/Actions/ScreenAction.swift`
- [Screen Navigator](https://github.com/hhru/nivelir/blob/main/Sources/Screen/Navigator/ScreenNavigator.swift): `Sources/Screen/Navigator/ScreenNavigator.swift`
- [UIKit Containers](https://github.com/hhru/nivelir/blob/main/Sources/Screen/Container/ScreenContainer.swift): `Sources/Screen/Container/ScreenContainer.swift`
- [Navigation Observation](https://github.com/hhru/nivelir/blob/main/Sources/Screen/Observation/ScreenObserver.swift): `Sources/Screen/Observation/ScreenObserver.swift`

### Deep Links

- [Link Inputs](https://github.com/hhru/nivelir/blob/main/Sources/Deeplink/URL/URLDeeplink.swift): `Sources/Deeplink/URL/URLDeeplink.swift`
- [Notification Links](https://github.com/hhru/nivelir/blob/main/Sources/Deeplink/Notification/NotificationDeeplink.swift): `Sources/Deeplink/Notification/NotificationDeeplink.swift`
- [Shortcut Links](https://github.com/hhru/nivelir/blob/main/Sources/Deeplink/Shortcut/ShortcutDeeplink.swift): `Sources/Deeplink/Shortcut/ShortcutDeeplink.swift`
- [Deep Link Manager](https://github.com/hhru/nivelir/blob/main/Sources/Deeplink/DeeplinkManager.swift): `Sources/Deeplink/DeeplinkManager.swift`
- [Link Interceptors](https://github.com/hhru/nivelir/blob/main/Sources/Deeplink/DeeplinkInterceptor.swift): `Sources/Deeplink/DeeplinkInterceptor.swift`
- [Link Storage](https://github.com/hhru/nivelir/blob/main/Sources/Deeplink/DeeplinkStorage.swift): `Sources/Deeplink/DeeplinkStorage.swift`

### UI Addons

- [Screen Addon Actions](https://github.com/hhru/nivelir/tree/main/Sources/Addons): `Sources/Addons`
- [Media Picker](https://github.com/hhru/nivelir/blob/main/Sources/Addons/MediaPicker/MediaPickerManager.swift): `Sources/Addons/MediaPicker/MediaPickerManager.swift`
- [Document Preview](https://github.com/hhru/nivelir/blob/main/Sources/Addons/DocumentPreview/DocumentPreviewManager.swift): `Sources/Addons/DocumentPreview/DocumentPreviewManager.swift`
- [Safari Launcher](https://github.com/hhru/nivelir/blob/main/Sources/Addons/Safari/SafariManager.swift): `Sources/Addons/Safari/SafariManager.swift`
- [Sharing](https://github.com/hhru/nivelir/blob/main/Sources/Addons/Sharing/Sharing.swift): `Sources/Addons/Sharing/Sharing.swift`
- [Progress HUD](https://github.com/hhru/nivelir/blob/main/Sources/Addons/HUD/HUD.swift): `Sources/Addons/HUD/HUD.swift`

### Bottom Sheet

- [Bottom Sheet API](https://github.com/hhru/nivelir/blob/main/Sources/Addons/BottomSheet/BottomSheet.swift): `Sources/Addons/BottomSheet/BottomSheet.swift`
- [Sheet Controller](https://github.com/hhru/nivelir/blob/main/Sources/Addons/BottomSheet/BottomSheetController.swift): `Sources/Addons/BottomSheet/BottomSheetController.swift`
- [Sheet Presentation](https://github.com/hhru/nivelir/blob/main/Sources/Addons/BottomSheet/Presentation/BottomSheetPresentationController.swift): `Sources/Addons/BottomSheet/Presentation/BottomSheetPresentationController.swift`
- [Detent Resolver](https://github.com/hhru/nivelir/blob/main/Sources/Addons/BottomSheet/Detention/BottomSheetDetentionController.swift): `Sources/Addons/BottomSheet/Detention/BottomSheetDetentionController.swift`
- [Gesture Interaction](https://github.com/hhru/nivelir/blob/main/Sources/Addons/BottomSheet/Interaction/BottomSheetInteractionController.swift): `Sources/Addons/BottomSheet/Interaction/BottomSheetInteractionController.swift`

### Decoding Tools

- [URL Query Decoder](https://github.com/hhru/nivelir/blob/main/Sources/Tools/URLQueryDecoder/URLQueryDecoder.swift): `Sources/Tools/URLQueryDecoder/URLQueryDecoder.swift`
- [Dictionary Decoder](https://github.com/hhru/nivelir/blob/main/Sources/Tools/DictionaryDecoder/DictionaryDecoder.swift): `Sources/Tools/DictionaryDecoder/DictionaryDecoder.swift`

### Other components

- **App**

## Connections

- App → Screen Definition: defines
- App → Route DSL: builds routes
- App → Screen Navigator: submits navigation
- Screen Navigator → UIKit Containers: finds containers (evidence: `Sources/Screen/Navigator/ScreenNavigator.swift`)
- Screen Navigator → Navigation Observation: supports observation (evidence: `Sources/Screen/Navigator/ScreenNavigator.swift`)
- Deep Link Manager → Screen Navigator: requests navigation (evidence: `Sources/Deeplink/DeeplinkManager.swift`)
- Deep Link Manager → Link Interceptors: runs interceptors (evidence: `Sources/Deeplink/DeeplinkManager.swift`)
- Deep Link Manager → Link Storage: stores resolved link (evidence: `Sources/Deeplink/DeeplinkManager.swift`)
- Deep Link Manager → URL Query Decoder: decodes URL query (evidence: `Sources/Deeplink/DeeplinkManager.swift`)
- Deep Link Manager → Dictionary Decoder: decodes payload (evidence: `Sources/Deeplink/DeeplinkManager.swift`)
- Media Picker → Screen Addon Actions: implements action (evidence: `Sources/Addons/MediaPicker/MediaPickerManager.swift`)
- Sheet Controller → Sheet Presentation: creates presentation (evidence: `Sources/Addons/BottomSheet/BottomSheetController.swift`)
- Sheet Presentation → Detent Resolver: resolves detents (evidence: `Sources/Addons/BottomSheet/Presentation/BottomSheetPresentationController.swift`)
- Sheet Presentation → Gesture Interaction: delegates gestures (evidence: `Sources/Addons/BottomSheet/Presentation/BottomSheetPresentationController.swift`)
- Sheet Controller → Bottom Sheet API: copies configuration (evidence: `Sources/Addons/BottomSheet/BottomSheetController.swift`)
- Link Inputs → Deep Link Manager: is resolved by
- Notification Links → Deep Link Manager: is resolved by
- Shortcut Links → Deep Link Manager: is resolved by
