# applidium/overlaycontainer architecture

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

- Interactive diagram: https://gitdiagram.com/applidium/overlaycontainer
- Repository: https://github.com/applidium/overlaycontainer

## Overview

##### Project type and purpose
- This is an iOS UI library (written in Swift) that provides an “overlay container” view controller for building draggable overlay interfaces (like Maps, Stocks, Shortcuts).
- It is packaged for CocoaPods/Carthage/SwiftPM and includes an Example app and a suite of unit tests.

##### High-level file structure
- Top-level packaging & CI:
- .github/… (issue templates, CI workflows)
- fastlane/… (release automation)
- Gemfile, Podspec, Package.swift, Package.resolved, Package.xcconfig
- Core library (Source/OverlayContainer + Internal/)
- Example app (Example/OverlayContainer_Example/)
- Tests (Tests/OverlayContainerTests/…)
- Assets, README, CHANGELOG, LICENSE

##### Core components
A. OverlayContainerViewController (entry point)
B. Child view controllers stack (“content” VCs + the topmost draggable “overlay” VC)
C. Internal view hierarchy:
1. Container view (OverlayContainerView)
2. Overlay translation views (OverlayTranslationContainerView, OverlayTranslationView)
3. Dimmer/backdrop view (OverlayContainerSheetDimmingView)
D. Gesture coordination and translation pipeline:
1. UIPanGestureRecognizer (built into the container)
2. OverlayTranslationDriver protocols & implementations
– PanGestureOverlayTranslationDriver
– ScrollViewOverlayTranslationDriver
3. OverlayTranslationFunction (strategy for rubber-band effect)
– RubberBandOverlayTranslationFunction (default)
4. OverlayTranslationTargetNotchPolicy (strategy for choosing the next notch)
– RushingForwardTargetNotchPolicy (default)
5. OverlayAnimatedTransitioning (strategy for animation)
– SpringOverlayTranslationAnimationController (default)
6. OverlayContainerTransitionCoordinator (delegate notification & animation hook)
E. Delegate interfaces (OverlayContainerViewControllerDelegate)
F. Packaging & distribution (CocoaPods/Carthage labels)
G. Example app layer (consumes the library via SPM/Pods, sets up `container.viewControllers` etc.)
H. Unit tests (drive TranslationControllers, Notch policies, Utility extensions)

##### Relationships & interactions
- The host app → imports the library → instantiates an OverlayContainerViewController
- The container VC → embeds child VCs → builds a view hierarchy of ContainerView + TranslationViews
- User pan/scroll gestures → routed to OverlayTranslationDriver → computes translation offset via OverlayTranslationFunction → asks TargetNotchPolicy for destination → invokes AnimatedTransitioning to animate → updates ContainerView’s y-position
- OverlayContainerViewControllerDelegate methods are called at each phase (willTranslate, willMove, didMove…) via OverlayContainerTransitionCoordinator
- The Example app → demonstrates setup scenarios, shows how to override delegates, attach to UINavigationController, present modally via a PresentationController subclass
- Tests → instantiate drivers/policies/functions → verify notch heights, rubber-band behavior, scroll coordination, etc.

##### Architectural patterns & design principles
- Protocol-oriented design (TranslationDriver, TranslationFunction, TargetNotchPolicy, AnimatedTransitioning)
- Strategy pattern for pluggable behaviors (translation math, notch policy, animations)
- Delegation for notifying client code (delegate callbacks & transition coordinator)
- Composition over inheritance (internal classes wired together at runtime)
- Clear separation: Core library vs. example app vs. tests vs. packaging/CI

##### Detail level
- Do not omit the OverlayContainerTransitionCoordinator—this is central for client code to hook animations
- How the delegate pattern weaves through the translation pipeline
- Packaging (CocoaPods/Carthage/SwiftPM) and CI (GitHub Actions, fastlane) externally to give context for distribution and quality assurance

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Client App
    subgraph "Client Application" 
        App["Host App"]:::app
    end

    %% Public API
    subgraph "Public API"
        VC["OverlayContainerViewController"]:::api
        Delegate["OverlayContainerViewControllerDelegate"]:::protocol
        TranslationFuncProto["OverlayTranslationFunction (protocol)"]:::protocol
        NotchPolicyProto["OverlayTranslationTargetNotchPolicy (protocol)"]:::protocol
        DriverProto["OverlayTranslationDriver (protocol)"]:::protocol
        AnimatorProto["OverlayAnimatedTransitioning (protocol)"]:::protocol
    end

    %% Internal Implementation
    subgraph "Core/Internal"
        subgraph "Views"
            ContainerView["OverlayContainerView"]:::view
            TransContView["OverlayTranslationContainerView"]:::view
            TransView["OverlayTranslationView"]:::view
            Dimmer["OverlayContainerSheetDimmingView"]:::view
        end
        subgraph "Gestures"
            PanUtils["UIPanGestureRecognizer+Utils"]:::util
            PanGR["OverlayTranslationGestureRecognizer"]:::util
        end
        subgraph "Drivers"
            PanDriver["PanGestureOverlayTranslationDriver"]:::driver
            ScrollDriver["ScrollViewOverlayTranslationDriver"]:::driver
        end
        subgraph "Functions"
            RubberFunc["RubberBandOverlayTranslationFunction"]:::function
        end
        subgraph "Policies"
            RushingPolicy["RushingForwardTargetNotchPolicy"]:::policy
        end
        subgraph "Animations"
            SpringAnim["SpringOverlayTranslationAnimationController"]:::anim
        end
        subgraph "Coordinators"
            TransitionCoord["OverlayContainerTransitionCoordinator"]:::coord
            DraggingCoord["DraggingOverlayContainerTransitionCoordinator"]:::coord
            InterruptCoord["InterruptibleAnimatorOverlayContainerTransitionCoordinator"]:::coord
        end
        Extensions["UIViewController+Children"]:::util
    end

    %% Packaging & CI
    subgraph "Packaging & CI"
        Podspec["OverlayContainer.podspec"]:::packaging
        SwiftPM["Package.swift"]:::packaging
        Gemfile["Gemfile"]:::packaging
        Fastlane["fastlane/"]:::packaging
        GitHub[".github/"]:::packaging
    end

    %% Example App
    subgraph "Example App"
        ExampleApp["OverlayContainer_Example"]:::example
    end

    %% Unit Tests
    subgraph "Unit Tests"
        TestsSuite["OverlayContainerTests"]:::test
    end

    %% Relationships
    App -->|"uses"| VC
    VC -->|"embeds children"| Extensions
    VC -->|"builds view hierarchy"| ContainerView
    ContainerView --> TransContView
    TransContView --> TransView
    ContainerView --> Dimmer

    ContainerView -->|"adds gesture recognizer"| PanGR
    PanUtils --> PanGR
    PanGR --> PanDriver
    PanGR --> ScrollDriver

    PanDriver -->|"uses"| RubberFunc
    ScrollDriver -->|"uses"| RubberFunc

    PanDriver -->|"asks"| RushingPolicy
    ScrollDriver -->|"asks"| RushingPolicy

    PanDriver -->|"animates via"| SpringAnim
    ScrollDriver -->|"animates via"| SpringAnim

    VC --> TransitionCoord
    TransitionCoord --> DraggingCoord
    TransitionCoord --> InterruptCoord
    VC -->|"delegate callbacks"| Delegate

    App --> ExampleApp
    ExampleApp -->|"instantiates"| VC

    TestsSuite --> PanDriver
    TestsSuite --> ScrollDriver
    TestsSuite --> RubberFunc
    TestsSuite --> RushingPolicy

    %% Click Events
    click VC "https://github.com/applidium/overlaycontainer/blob/main/Source/OverlayContainer/OverlayContainerViewController.swift"
    click Extensions "https://github.com/applidium/overlaycontainer/blob/main/Source/OverlayContainer/Internal/Extensions/UIViewController+Children.swift"
    click ContainerView "https://github.com/applidium/overlaycontainer/blob/main/Source/OverlayContainer/Internal/Views/OverlayContainerView.swift"
    click TransContView "https://github.com/applidium/overlaycontainer/blob/main/Source/OverlayContainer/Internal/Views/OverlayTranslationContainerView.swift"
    click TransView "https://github.com/applidium/overlaycontainer/blob/main/Source/OverlayContainer/Internal/Views/OverlayTranslationView.swift"
    click Dimmer "https://github.com/applidium/overlaycontainer/blob/main/Source/OverlayContainer/OverlayContainerSheetDimmingView.swift"
    click PanUtils "https://github.com/applidium/overlaycontainer/blob/main/Source/OverlayContainer/Internal/Extensions/UIPanGesture+Utils.swift"
    click PanGR "https://github.com/applidium/overlaycontainer/blob/main/Source/OverlayContainer/Internal/OverlayTranslationGestureRecognizer.swift"
    click DriverProto "https://github.com/applidium/overlaycontainer/blob/main/Source/OverlayContainer/Internal/OverlayTranslationDriver.swift"
    click PanDriver "https://github.com/applidium/overlaycontainer/blob/main/Source/OverlayContainer/Internal/PanGestureOverlayTranslationDriver.swift"
    click ScrollDriver "https://github.com/applidium/overlaycontainer/blob/main/Source/OverlayContainer/Internal/ScrollViewOverlayTranslationDriver.swift"
    click TranslationFuncProto "https://github.com/applidium/overlaycontainer/blob/main/Source/OverlayContainer/OverlayTranslationFunction.swift"
    click RubberFunc "https://github.com/applidium/overlaycontainer/blob/main/Source/OverlayContainer/RubberBandOverlayTranslationFunction.swift"
    click NotchPolicyProto "https://github.com/applidium/overlaycontainer/blob/main/Source/OverlayContainer/RushingForwardTargetNotchPolicy.swift"
    click RushingPolicy "https://github.com/applidium/overlaycontainer/blob/main/Source/OverlayContainer/RushingForwardTargetNotchPolicy.swift"
    click AnimatorProto "https://github.com/applidium/overlaycontainer/blob/main/Source/OverlayContainer/SpringOverlayTranslationAnimationController.swift"
    click SpringAnim "https://github.com/applidium/overlaycontainer/blob/main/Source/OverlayContainer/SpringOverlayTranslationAnimationController.swift"
    click TransitionCoord "https://github.com/applidium/overlaycontainer/blob/main/Source/OverlayContainer/OverlayContainerTransitionCoordinator.swift"
    click DraggingCoord "https://github.com/applidium/overlaycontainer/blob/main/Source/OverlayContainer/Internal/DraggingOverlayContainerTransitionCoordinator.swift"
    click InterruptCoord "https://github.com/applidium/overlaycontainer/blob/main/Source/OverlayContainer/Internal/InterruptibleAnimatorOverlayContainerTransitionCoordinator.swift"
    click Delegate "https://github.com/applidium/overlaycontainer/blob/main/Source/OverlayContainer/OverlayContainerViewControllerDelegate.swift"
    click Podspec "https://github.com/applidium/overlaycontainer/blob/main/OverlayContainer.podspec"
    click SwiftPM "https://github.com/applidium/overlaycontainer/blob/main/Package.swift"
    click Gemfile "https://github.com/applidium/overlaycontainer/tree/main/Gemfile"
    click Fastlane "https://github.com/applidium/overlaycontainer/tree/main/fastlane/"
    click GitHub "https://github.com/applidium/overlaycontainer/tree/main/.github/"
    click ExampleApp "https://github.com/applidium/overlaycontainer/tree/main/Example/OverlayContainer_Example/"
    click TestsSuite "https://github.com/applidium/overlaycontainer/tree/main/Tests/OverlayContainerTests/"

    %% Styles
    classDef api fill:#D6EAF8,stroke:#3498DB;
    classDef protocol fill:#EBF5FB,stroke:#5DADE2,stroke-dasharray:5 5;
    classDef view fill:#FDEBD0,stroke:#EB984E;
    classDef util fill:#E8DAEF,stroke:#A569BD;
    classDef driver fill:#D5F5E3,stroke:#27AE60;
    classDef function fill:#FCF3CF,stroke:#F1C40F;
    classDef policy fill:#FADBD8,stroke:#E74C3C;
    classDef anim fill:#E8F8F5,stroke:#1ABC9C;
    classDef coord fill:#FEF9E7,stroke:#F39C12;
    classDef app fill:#E8F6F3,stroke:#1ABC9C;
    classDef packaging fill:#FEF5E7,stroke:#D35400;
    classDef example fill:#F4ECF7,stroke:#8E44AD,stroke-dasharray:5 5;
    classDef test fill:#F5EEF8,stroke:#884EA0,stroke-dasharray:5 5;
```
