# sarthurx/vector-chat architecture

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

- Interactive diagram: https://gitdiagram.com/sarthurx/vector-chat
- Repository: https://github.com/sarthurx/vector-chat

## Overview

##### Project type and purpose
- This is an iOS SwiftUI application (“vector-chat”) whose core purpose is peer-to-peer ranging and directional measurement using Apple’s NearbyInteraction (UWB) framework. It discovers and connects two devices, exchanges discovery tokens, and then initiates a UWB session to measure distance and direction in real time.

##### File structure
- Top-level:
- vector-chat.xcodeproj & related Xcode workspace files
- vector-chat/            ← main SwiftUI app target
- vector-chatTests/       ← unit tests
- vector-chatUITests/     ← UI tests
- In vector-chat/:
- vector_chatApp.swift    ← @main SwiftUI App entry point
- NearbyInteractionManager.swift ← encapsulates NI session setup, token exchange, callbacks
- PointerView.swift, RadarView.swift ← SwiftUI views that render UI based on UWB data
- vector-chat.entitlements ← declares NearbyInteraction and Multipeer-Connectivity capabilities
- Assets.xcassets, Info.plist

##### Insights from README
- The README shows the peer-to-peer flow:
a. Device A starts advertising & browsing (MultipeerConnectivity)
b. It waits for invites, invites Device B
c. They exchange discovery tokens over the Multipeer link
d. NearbyInteraction session starts for UWB ranging & direction

##### Main components
a. SwiftUI Layer
– vector_chatApp.swift (App entry)
– RadarView, PointerView (UI updates)
b. NearbyInteractionManager
– Responsible for:
- Starting/stopping MultipeerConnectivity advertising & browsing
- Sending/receiving discovery tokens
- Setting up NI session (start, delegate callbacks)
c. Apple Frameworks (external services)
– MultipeerConnectivity.framework ← peer discovery & token exchange channel
– NearbyInteraction.framework ← UWB ranging & directional data
d. Device Hardware
– UWB radio (for distance & direction measurement)
– Local device OS (iOS Core)

##### Relationships & interactions
- UI Layer ↔ NearbyInteractionManager
- UI invokes “startScanning()”, “invitePeer()”
- Manager emits published properties (distance, angle) → SwiftUI views
- Manager ↔ MultipeerConnectivity
- Advertise/browse → establish MCSession
- Exchange discovery tokens over MCSession data channel
- Manager ↔ NearbyInteraction.framework
- Create NISession with peer’s token
- Receive NINearbyObject updates (distance, direction)
- NearbyInteraction.framework ↔ UWB hardware

##### Architectural patterns & principles
- MVVM-style separation: SwiftUI views bind to published state in the Manager
- Single-responsibility: NearbyInteractionManager isolates all peer/connect/ranging logic
- Reactive updates: SwiftUI + Combine (or @Published) for real-time UI refresh

##### Essential checklist
- Both devices (Device A and Device B) side by side
- Sequence: advertise/browse → invite/connect → token exchange → UWB ranging

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Local Device
    subgraph "Local Device"
        direction TB
        L_SwiftUI["SwiftUI App"]:::ui
        L_Radar["RadarView"]:::ui
        L_Pointer["PointerView"]:::ui
        L_SwiftUI -->|"binds to @Published"| L_Radar
        L_SwiftUI -->|"binds to @Published"| L_Pointer
        L_SwiftUI -->|"invoke startScanning()/invitePeer()"| L_Manager
        L_Radar -->|"reads distance & angle"| L_Manager
        L_Pointer -->|"reads distance & angle"| L_Manager
        L_Manager["NearbyInteractionManager"]:::core
    end

    %% Remote Device
    subgraph "Remote Device"
        direction TB
        R_SwiftUI["SwiftUI App"]:::ui
        R_Radar["RadarView"]:::ui
        R_Pointer["PointerView"]:::ui
        R_Manager["NearbyInteractionManager"]:::core
        R_SwiftUI -->|"invoke startScanning()/invitePeer()"| R_Manager
        R_SwiftUI -->|"binds to @Published"| R_Radar
        R_SwiftUI -->|"binds to @Published"| R_Pointer
        R_Radar -->|"reads distance & angle"| R_Manager
        R_Pointer -->|"reads distance & angle"| R_Manager
    end

    %% Frameworks & Hardware
    MC["MultipeerConnectivity.framework"]:::fw
    NI["NearbyInteraction.framework"]:::fw
    HW_L["UWB Hardware"]:::hw
    HW_R["UWB Hardware"]:::hw

    %% App Resources
    subgraph "App Resources"
        direction TB
        Entitlements["vector-chat.entitlements"]:::fw
        Assets["Assets.xcassets"]:::fw
        Info["Info.plist"]:::fw
        Tests["Unit Tests"]:::test
        UITests["UI Tests"]:::test
    end

    %% Connections
    L_Manager -->|"advertise/browse"| MC
    MC -->|"DiscoveryToken"| R_Manager
    R_Manager -->|"advertise/browse"| MC
    L_Manager -->|"create NISession(token)"| NI
    NI -->|"NINearbyObject(distance, direction)"| L_Manager
    NI -->|"radio link"| HW_L
    NI -->|"radio link"| HW_R
    R_Manager -->|"create NISession(token)"| NI
    NI -->|"NINearbyObject(distance, direction)"| R_Manager

    %% Click Events
    click L_SwiftUI "https://github.com/sarthurx/vector-chat/blob/main/vector-chat/vector_chatApp.swift"
    click L_Radar "https://github.com/sarthurx/vector-chat/blob/main/vector-chat/RadarView.swift"
    click L_Pointer "https://github.com/sarthurx/vector-chat/blob/main/vector-chat/PointerView.swift"
    click L_Manager "https://github.com/sarthurx/vector-chat/blob/main/vector-chat/NearbyInteractionManager.swift"
    click Entitlements "https://github.com/sarthurx/vector-chat/blob/main/vector-chat/vector-chat.entitlements"
    click Assets "https://github.com/sarthurx/vector-chat/blob/main/vector-chat/Assets.xcassets"
    click Info "https://github.com/sarthurx/vector-chat/blob/main/vector-chat/Info.plist"
    click Tests "https://github.com/sarthurx/vector-chat/blob/main/vector-chatTests/vector_chatTests.swift"
    click UITests "https://github.com/sarthurx/vector-chat/blob/main/vector-chatUITests/vector_chatUITests.swift"

    %% Styles
    classDef ui fill:#D2E4FC,stroke:#1B4F72,color:#0B2340
    classDef core fill:#D5ECD1,stroke:#305324,color:#1D3418
    classDef fw fill:#FFEAC2,stroke:#A66502,color:#5A3800
    classDef hw fill:#E0E0E0,stroke:#565656,color:#1A1A1A
    classDef test fill:#F3E5F5,stroke:#6A1B9A,color:#4A0072
```
