# grishka/neardrop architecture

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

- Interactive diagram: https://gitdiagram.com/grishka/neardrop
- Repository: https://github.com/grishka/neardrop

## Overview

##### Main Components
- Main Application (NearDrop folder): This is the core macOS app. It includes the AppDelegate, UI components (such as MainMenu.xib), and assets (in Assets.xcassets). It is responsible for general app behavior (menu bar integration, file saving, localization, etc.).
- NearbyShare Module (NearbyShare folder): This module holds the underlying connection logic and protobuf message handling. It includes code for inbound/outbound nearby connections, a connection manager, and scripts/generation for protobuf – essential for communication with Android devices.
- Share Extension (ShareExtension folder): This component integrates with the macOS sharing interface (the “Share” menu in Finder, Safari, etc.). It contains its own assets, localized strings, and a user interface (via xib files) for choosing a device and initiating file transfers.
- Protocol & Documentation: The PROTOCOL.md file and embedded protobuf definitions/documentation (both Swift generated and proto source files) indicate how devices communicate using wire formats.

##### Out Relationships and Interactions
- User Interactions:
- The user interacts with the NearDrop menu bar app (which may include casual notifications or quick activation).
- When a user shares a file (right-click in Finder or via Safari), the ShareExtension is invoked, and it communicates with the main application backend.
- Communication Flow:
- The ShareExtension sends the file/share request to the core logic – likely by invoking functions in the NearbyShare module.
- The NearbyShare module handles the network logic, using Wi-Fi LAN (as stated in the README) to establish peer connections to Android devices. This module also processes the protobuf messages that adhere to the defined protocols.
- The connection status, successful transfers, and notifications are passed back to the main app which ultimately manages user feedback and saving files to the Downloads folder.

##### Architectural Patterns and Technologies
- Separation of Concerns: Notice the distinction between UI components (Main app and ShareExtension) and the underlying network/connection logic contained within the NearbyShare module.
- Modular Design: The project is divided into clear modules (main app, share extension, and network communication module), making it easier to see boundaries and responsibilities.
- Use of Protobuf for Message Serialization: The presence of both generated Swift protobuf files and their corresponding proto source files indicates a message-based protocol for secure communication.
- Localization: Multiple language-specific resource directories indicate that the UI components support internationalization.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Menu Bar App (NearDrop)"
        AppDelegate("AppDelegate"):::mainApp
        MainMenu("MainMenu.xib"):::mainApp
        Assets("Assets.xcassets"):::mainApp
        Localization("Localized Strings"):::mainApp
    end

    subgraph "NearbyShare Module"
        Inbound("InboundNearbyConnection"):::network
        Outbound("OutboundNearbyConnection"):::network
        ConnectionManager("NearbyConnectionManager"):::network
        DataExtensions("Data+Extensions"):::network
        ProtobufHandling("Protobuf Handling"):::network
        ProtobufSource("Protobuf Source"):::network
        GenerateProtobuf("GenerateProtobuf.sh"):::network
    end

    subgraph "Share Extension"
        ShareView("ShareViewController"):::shareExt
        DeviceCell("DeviceListCell"):::shareExt
        ShareViewUI("ShareViewController.xib"):::shareExt
        DeviceCellUI("DeviceListCell.xib"):::shareExt
        ShareAssets("Assets (ShareExtension)"):::shareExt
        SELocalization("Localized Resources"):::shareExt
    end

    subgraph "Protocol & Documentation"
        ProtocolDoc("PROTOCOL.md"):::protocol
    end

    AndroidDevice("External: Android Device"):::external

    %% Connections between components
    ShareView -->|"FileShareRequest"| AppDelegate
    ShareView -->|"InvokeNearbyShare"| ConnectionManager
    AppDelegate -->|"InitiateConnection"| ConnectionManager
    ConnectionManager -->|"Control_Inbound"| Inbound
    ConnectionManager -->|"Control_Outbound"| Outbound
    Inbound -->|"SendsStatus"| AppDelegate
    Outbound -->|"ReceivesData"| AppDelegate
    ConnectionManager -->|"DataExchange"| AndroidDevice
    ConnectionManager -->|"HandlesProtobuf"| ProtobufHandling
    ProtobufHandling -->|"UsesProtocol"| ProtocolDoc

    %% Styles
    classDef mainApp fill:#f9e79f,stroke:#d4ac0d,stroke-width:2px;
    classDef network fill:#aed6f1,stroke:#2471a3,stroke-width:2px;
    classDef shareExt fill:#d5f5e3,stroke:#27ae60,stroke-width:2px;
    classDef external fill:#fadbd8,stroke:#c0392b,stroke-width:2px;
    classDef protocol fill:#f5cba7,stroke:#af601a,stroke-width:2px;

    %% Click Events for Main Application nodes
    click AppDelegate "https://github.com/grishka/neardrop/blob/master/NearDrop/AppDelegate.swift"
    click MainMenu "https://github.com/grishka/neardrop/blob/master/NearDrop/MainMenu.xib"
    click Assets "https://github.com/grishka/neardrop/blob/master/NearDrop/Assets.xcassets"
    click Localization "https://github.com/grishka/neardrop/blob/master/NearDrop/Base.lproj"

    %% Click Events for NearbyShare module nodes
    click Inbound "https://github.com/grishka/neardrop/blob/master/NearbyShare/InboundNearbyConnection.swift"
    click Outbound "https://github.com/grishka/neardrop/blob/master/NearbyShare/OutboundNearbyConnection.swift"
    click ConnectionManager "https://github.com/grishka/neardrop/blob/master/NearbyShare/NearbyConnectionManager.swift"
    click DataExtensions "https://github.com/grishka/neardrop/blob/master/NearbyShare/Data+Extensions.swift"
    click ProtobufHandling "https://github.com/grishka/neardrop/tree/master/NearbyShare/Protobuf"
    click ProtobufSource "https://github.com/grishka/neardrop/tree/master/NearbyShare/ProtobufSource"
    click GenerateProtobuf "https://github.com/grishka/neardrop/blob/master/NearbyShare/GenerateProtobuf.sh"

    %% Click Events for Share Extension nodes
    click ShareView "https://github.com/grishka/neardrop/blob/master/ShareExtension/ShareViewController.swift"
    click DeviceCell "https://github.com/grishka/neardrop/blob/master/ShareExtension/DeviceListCell.swift"
    click ShareViewUI "https://github.com/grishka/neardrop/blob/master/ShareExtension/Base.lproj/ShareViewController.xib"
    click DeviceCellUI "https://github.com/grishka/neardrop/blob/master/ShareExtension/DeviceListCell.xib"
    click ShareAssets "https://github.com/grishka/neardrop/blob/master/ShareExtension/Assets.xcassets"
    click SELocalization "https://github.com/grishka/neardrop/blob/master/ShareExtension/Base.lproj"

    %% Click Event for Protocol & Documentation
    click ProtocolDoc "https://github.com/grishka/neardrop/blob/master/PROTOCOL.md"
```
