# aeastr/portal architecture

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

- Interactive diagram: https://gitdiagram.com/aeastr/portal
- Repository: https://github.com/aeastr/portal

## Overview

##### Project type and purpose
- This is a Swift Package library (not a full-stack app) that provides a set of SwiftUI view modifiers and container components to drive “portal”-style view transitions (floating animations) across view hierarchies, sheets, and navigation pushes.

##### File structure
- Top-level:
- Package.swift, README.md, LICENSE, Tests, Sources
- .github/workflows – CI setup for building/testing on Swift toolchains
- Sources/Portal:
- Core API / data types: AnchorKey.swift, CrossModel.swift, PortalInfo.swift
- Container/engine components: PortalContainer.swift, PassThroughWindow.swift, PortalLayerView.swift
- Public SwiftUI view modifiers and helpers: PortalSource.swift, PortalDestination.swift, PortalTransition.swift, SheetShow.swift, View+OnChangeCompat.swift
- Examples subfolder: CardsExample.swift, DifferExample.swift, NavigationExample.swift, SheetExample.swift
- Tests/PortalTests: unit tests for SheetShow behavior

##### README for additional insights
- Emphasizes a portal metaphor, SwiftUI compatibility (iOS 15+), no custom presentation modifiers required, and a small set of public APIs: .portalContainer(), .portalSource(…), .portalDestination(…), .portalTransition(…).

##### Main components
a. SwiftUI App (consumer)
b. PortalContainer
c. View hierarchy containing:
- PortalSource anchors
- PortalDestination anchors
- PortalTransition controllers (Binding<Bool> or Binding<Item?>)
d. Core engine:
- PortalInfo registry (maps source/destination IDs to view anchor info)
- CrossModel (coordinate conversion logic)
- AnchorKey (preference key for gathering anchor frames)
e. Overlay layer:
- PassThroughWindow (UIWindow subclass to host overlay above existing hierarchy)
- PortalLayerView (SwiftUI view that renders the floating snapshot and animates)
f. Examples & Tests (auxiliary components)

##### Relationships & data flow
1. App wraps its root in `PortalContainer` → installs `PassThroughWindow` + `.environmentObject(PortalInfo)`.
2. A view marked with `.portalSource(id:)` publishes its anchor frame via `AnchorKey` into `PortalInfo` registry.
3. A separate view marked with `.portalDestination(id:)` also publishes its target anchor frame.
4. When `.portalTransition(isActive: id:)` becomes true, the controller:
- Reads source & destination frames from `PortalInfo`
- Generates a snapshot or moves the source view into `PortalLayerView`
- Animates its frame/scale across hierarchies using `CrossModel` coordinate conversions
- On completion, reintegrates the view into the destination location
5. `PortalLayerView` lives in `PassThroughWindow`, rendered above everything.

##### Architectural patterns & design principles
- SwiftUI + PreferenceKey pattern for gathering layout information (`AnchorKey`)
- EnvironmentObject (`PortalInfo`) for cross-hierarchy state sharing
- UIWindow overlay (PassThroughWindow) for out-of-tree rendering
- Decoupled source/destination registration & controller-driven animation
- Pure Swift Package (platform-agnostic, no storyboard or XIBs)

##### Details
- To show the separation of concerns: registration vs animation vs rendering
- How SwiftUI’s PreferenceKey and EnvironmentObject work together
- Don’t omit the overlay window: it’s the heart of cross-hierarchy transitions
- Example entry points to illustrate real-world usage paths

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Consumer Application Layer
    App["SwiftUI App (Consumer)"]:::external
    App -->|"wraps root in"| PortalContainer

    %% Container and State Layer
    subgraph "Container Layer"
        PortalContainer["PortalContainer"]:::external
        PortalContainer -->|"installs and envObject"| PortalInfo
        PortalContainer --> PassThroughWindow
    end

    PortalInfo[(PortalInfo)]:::state

    %% Core Engine
    subgraph "Core Engine" 
        AnchorKey["AnchorKey"]:::core
        CrossModel["CrossModel"]:::core
    end

    %% Public API Modifiers
    subgraph "Public API" 
        PortalSource["PortalSource"]:::publicAPI
        PortalDestination["PortalDestination"]:::publicAPI
        PortalTransition["PortalTransition"]:::publicAPI
        SheetShow["SheetShow"]:::publicAPI
        ViewOnChange["View+OnChangeCompat"]:::publicAPI
    end

    %% Rendering Overlay
    subgraph "Rendering Layer"
        PassThroughWindow["PassThroughWindow"]:::render
        PortalLayerView["PortalLayerView"]:::render
    end

    %% Examples and Tests
    subgraph "Examples & Tests"
        Examples["Examples"]:::example
        Tests["SheetShowTests"]:::example
    end

    %% Data Flows
    PortalSource -->|"uses"| AnchorKey
    AnchorKey -->|"publishes anchor frames"| PortalInfo
    PortalDestination -->|"uses"| AnchorKey
    AnchorKey -->|"publishes anchor frames"| PortalInfo
    PortalTransition -->|"reads registry"| PortalInfo
    PortalTransition -->|"uses"| CrossModel
    PortalTransition -->|"animates via"| PortalLayerView
    PortalLayerView --> PassThroughWindow

    %% Example and Tests interactions
    Examples --> PortalSource
    Examples --> PortalDestination
    Examples --> PortalTransition
    Tests --> SheetShow

    %% Click Events
    click PortalContainer "https://github.com/aeastr/portal/blob/main/Sources/Portal/PortalContainer.swift"
    click PortalInfo "https://github.com/aeastr/portal/blob/main/Sources/Portal/PortalInfo.swift"
    click AnchorKey "https://github.com/aeastr/portal/blob/main/Sources/Portal/AnchorKey.swift"
    click CrossModel "https://github.com/aeastr/portal/blob/main/Sources/Portal/CrossModel.swift"
    click PassThroughWindow "https://github.com/aeastr/portal/blob/main/Sources/Portal/PassThroughWindow.swift"
    click PortalLayerView "https://github.com/aeastr/portal/blob/main/Sources/Portal/PortalLayerView.swift"
    click PortalSource "https://github.com/aeastr/portal/blob/main/Sources/Portal/PortalSource.swift"
    click PortalDestination "https://github.com/aeastr/portal/blob/main/Sources/Portal/PortalDestination.swift"
    click PortalTransition "https://github.com/aeastr/portal/blob/main/Sources/Portal/PortalTransition.swift"
    click SheetShow "https://github.com/aeastr/portal/blob/main/Sources/Portal/SheetShow.swift"
    click ViewOnChange "https://github.com/aeastr/portal/blob/main/Sources/Portal/View+OnChangeCompat.swift"
    click Examples "https://github.com/aeastr/portal/tree/main/Sources/Portal/Examples"
    click Tests "https://github.com/aeastr/portal/blob/main/Tests/PortalTests/SheetShowTests.swift"

    %% Styles
    classDef publicAPI fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef core fill:#90EE90,stroke:#333,stroke-width:1px
    classDef render fill:#DDA0DD,stroke:#333,stroke-width:1px
    classDef example fill:#D3D3D3,stroke:#333,stroke-width:1px
    classDef state fill:#FFFACD,stroke:#333,stroke-width:1px
    classDef external fill:#EFEFEF,stroke:#333,stroke-width:1px
```
