# btbishop93/braver-search architecture

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

- Interactive diagram: https://gitdiagram.com/btbishop93/braver-search
- Repository: https://github.com/btbishop93/braver-search

## Overview

- Browser Environment: Represent Safari (on iOS/macOS) where the extension runs.
- Extension Core:
- Background Script (“background.js” in Shared (Extension))
- Popup Interface Components (“popup.html”, “popup.css”, “popup.js”)
- Native Integration:
- SafariWebExtensionHandler.swift that bridges the extension’s functionalities into native code.
- Host Applications:
- iOS App (in “iOS (App)” and “iOS (Extension)” directories)
- macOS App (in “macOS (App)” and “macOS (Extension)” directories)
- Shared Codebases:
- Shared (App) for common application logic.
- Shared (Extension) for common extension resources and functionality.
- Supporting Layers:
- Tests (unit tests and integration tests in the Tests directory for JavaScript and native code)
- CI/CD Workflow using GitHub Actions (shown as external deployment pipelines and integration systems that handle code signing, building, and deployment)

##### Relationships and Interactions
- From Safari’s web navigation events (originating in the browser environment) to the background script that intercepts and redirects search queries.
- Native bridge (SafariWebExtensionHandler.swift) connecting the Web Extension to the iOS/macOS native layer.
- Interactions for:
- Code Signing, provisioning profiles, and deployment pipelines (GitHub Actions) which ensure the app/app extension is built and distributed correctly.
- Communication from the host applications (iOS/macOS) to the shared app logic supporting the extension and vice versa.

##### Architectural Patterns
- Modularity: The separation of “App” and “Extension” code into platform-specific and shared directories.
- Event-driven handling: The background script monitors and intercepts browser events.
- Native integration: A dedicated bridge (SafariWebExtensionHandler) ensures the extension is tightly integrated with Safari.
- CI/CD automation: GitHub Actions workflows handle automated building, signing, and deployment steps.

##### Technical Details and Technologies
- Xcode project elements (e.g., project.pbxproj and scheme files) indicate a reliance on Xcode for building and a manual code signing setup.
- Technologies: JavaScript (for the extension’s core logic and popup UI), Swift (for iOS/macOS native integration), CSS/HTML for the popup interface.
- Deployment details: Certificates, provisioning profiles, and App Store Connect API keys are managed via CI/CD (GitHub Actions), so include that in a separate “deployment pipeline” section if desired.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Global Components
    Browser["Safari Browser Environment"]:::browser

    %% Extension Core Subgraph
    subgraph "Extension Core"
        BGS["Background Script (background.js)"]:::web
        PopupHTML["Popup Interface (popup.html)"]:::popup
        PopupCSS["Popup Interface (popup.css)"]:::popup
        PopupJS["Popup Interface (popup.js)"]:::popup
    end

    %% Native Integration
    Native["Native Bridge (SafariWebExtensionHandler.swift)"]:::native

    %% Shared Codebases Subgraph
    subgraph "Shared Codebases"
        SharedApp["Shared Application Logic"]:::shared
        SharedExt["Shared Extension Resources"]:::shared
    end

    %% Host Applications Subgraph
    subgraph "Host Applications"
        subgraph "iOS"
            iOSApp["iOS App (Host)"]:::native
            iOSExt["iOS Extension"]:::native
        end
        subgraph "macOS"
            macOSApp["macOS App (Host)"]:::native
            macOSExt["macOS Extension"]:::native
        end
    end

    %% Supporting Layers Subgraph
    subgraph "Supporting Layers"
        TestsJS["JavaScript Tests"]:::test
        TestsIOS["Native Code Tests (iOS)"]:::test
        TestsMacOS["Native Code Tests (macOS)"]:::test
        CICD["CI/CD Workflow"]:::cicd
    end

    %% Data Flow Connections
    Browser -->|"triggers"| BGS
    PopupHTML <-->|"sync"| BGS
    PopupCSS <-->|"sync"| BGS
    PopupJS <-->|"sync"| BGS
    BGS -->|"bridges"| Native
    Native -->|"integrates"| iOSApp
    Native -->|"integrates"| macOSApp
    iOSApp -->|"uses"| SharedApp
    macOSApp -->|"uses"| SharedApp
    BGS -->|"utilizes"| SharedExt
    iOSExt -->|"utilizes"| SharedExt
    macOSExt -->|"utilizes"| SharedExt
    TestsJS -->|"tests"| BGS
    TestsIOS -->|"tests"| iOSApp
    TestsMacOS -->|"tests"| macOSApp
    CICD -->|"deploys"| iOSApp
    CICD -->|"deploys"| macOSApp
    CICD -->|"runs"| TestsJS
    CICD -->|"runs"| TestsIOS
    CICD -->|"runs"| TestsMacOS

    %% Click Events
    click BGS "https://github.com/btbishop93/braver-search/blob/main/Braver Search/Shared (Extension)/Resources/background.js"
    click PopupHTML "https://github.com/btbishop93/braver-search/blob/main/Braver Search/Shared (Extension)/Resources/popup.html"
    click PopupCSS "https://github.com/btbishop93/braver-search/blob/main/Braver Search/Shared (Extension)/Resources/popup.css"
    click PopupJS "https://github.com/btbishop93/braver-search/blob/main/Braver Search/Shared (Extension)/Resources/popup.js"
    click Native "https://github.com/btbishop93/braver-search/blob/main/Braver Search/Shared (Extension)/SafariWebExtensionHandler.swift"
    click iOSApp "https://github.com/btbishop93/braver-search/tree/main/Braver Search/iOS (App)"
    click iOSExt "https://github.com/btbishop93/braver-search/tree/main/Braver Search/iOS (Extension)"
    click macOSApp "https://github.com/btbishop93/braver-search/tree/main/Braver Search/macOS (App)"
    click macOSExt "https://github.com/btbishop93/braver-search/tree/main/Braver Search/macOS (Extension)"
    click SharedApp "https://github.com/btbishop93/braver-search/tree/main/Braver Search/Shared (App)"
    click SharedExt "https://github.com/btbishop93/braver-search/tree/main/Braver Search/Shared (Extension)"
    click TestsJS "https://github.com/btbishop93/braver-search/tree/main/Braver Search/Tests/JavaScript"
    click TestsIOS "https://github.com/btbishop93/braver-search/tree/main/Braver Search/Braver Search iOS Tests"
    click TestsMacOS "https://github.com/btbishop93/braver-search/tree/main/Braver Search/Braver Search macOS Tests"
    click CICD "https://github.com/btbishop93/braver-search/tree/main/.github/workflows"

    %% Styles
    classDef browser fill:#ffe0b3,stroke:#cc6600,stroke-width:2px;
    classDef web fill:#cce5ff,stroke:#3366cc,stroke-width:2px;
    classDef popup fill:#d1e7dd,stroke:#0f5132,stroke-width:2px;
    classDef native fill:#f8d7da,stroke:#a71d2a,stroke-width:2px;
    classDef shared fill:#e2e3e5,stroke:#41464b,stroke-width:2px;
    classDef test fill:#fff3cd,stroke:#856404,stroke-width:2px;
    classDef cicd fill:#d1c4e9,stroke:#673ab7,stroke-width:2px;
```
