# tej-sharma/horizon-overlay architecture

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

- Interactive diagram: https://gitdiagram.com/tej-sharma/horizon-overlay
- Repository: https://github.com/tej-sharma/horizon-overlay

## Overview

##### Project type and purpose
- This is a native macOS client application written in Swift/SwiftUI (“Constella Horizon”).
- Its main purpose is to capture screen content (OCR), send it to a backend AI service for context, and display that context in floating overlays. It also handles note/tag management via a REST/WebSocket API.

##### File structure
- Top-level Swift modules:
- AI: manages OCR/screenshots and AI service connections (AIContextManager, AIConnectionManager, TagWebSocketManager).
- API: REST client (APIClient, APIConfig) and WebSocket manager plus endpoints (ContextSearchAPI, NotesAPI).
- Auth: authentication/token management.
- ScreenParsing: captures windows/screenshots.
- InputEvent: global keyboard shortcut handling.
- Overlay: the various floating windows and views (AIAssist, QuickCapture, ExternalWindowOverlay).
- Setup & Settings: onboarding, permission flow, and preferences UI.
- SystemMenu: menu bar integration.
- CustomView, Utility, Models: shared widgets and data types.
- The entry point is ConstellaHorizonApp.swift.

##### README for additional insights
- Core features:
- Horizon Overlay – detection-free windows for privacy.
- AI Context Manager – OCR + screenshot pipeline.
- Window Overlay Managers – display logic for each overlay.
- Input Manager – keyboard event capture.
- Onboarding – permission prompts and user guide.

##### Diagramming recommendations
- Shortcut → Capture → OCR → REST/WS → Overlay UI
- AuthManager → APIClient/WebSocketManager
- Blue = UI/Overlay
- Green = Processing (OCR, Context)
- Orange = API/Auth
- Gray = System (Input, ScreenCapture)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% App Entry
    AppEntry["ConstellaHorizonApp"]:::ui

    %% UI Layer
    subgraph "UI & Overlay" 
        direction TB
        SystemMenu["SystemMenuManager"]:::ui
        subgraph "Setup & Onboarding"
            direction TB
            SetupView["SetupView"]:::ui
            SetupWC["SetupWindowController"]:::ui
            WelcomeView["WelcomeView"]:::ui
            PermissionTemplate["PermissionTemplateView"]:::ui
            FloatingOnboarding["FloatingOnboardingTemplate"]:::ui
            PermissionManager["PermissionManager"]:::ui
            ShortcutTF["ShortcutTextField"]:::ui
        end
        subgraph "Settings"
            direction TB
            SettingsView["SettingsView"]:::ui
            SettingsWC["SettingsWindowController"]:::ui
            SettingsModel["SettingsModel"]:::ui
        end
        subgraph "Overlays"
            direction TB
            AIAssistMgr["AIAssistOverlayManager"]:::ui
            AIAssistView["AIAssistView"]:::ui
            AIAssistWC["AIAssistWindowController"]:::ui
            QuickCapture["QuickCaptureOverlay"]:::ui
            ExternalWindowMgr["ExternalWindowOverlayManager"]:::ui
            AutoContext["AutoContextOverlay"]:::ui
            MainView["MainView"]:::ui
            MainWindow["MainWindow"]:::ui
            ContextCard["ContextCard"]:::ui
            TagChip["TagChip"]:::ui
        end
    end

    %% Input Layer
    subgraph "Input Layer"
        direction TB
        InputMgr["InputEventManager"]:::system
        ShortcutDefs["ShortcutDefinitions"]:::system
    end

    %% Screen Capture & OCR
    subgraph "Capture & OCR" 
        direction TB
        WindowCap["WindowCaptureManager"]:::system
        AIContext["AIContextManager"]:::processing
    end

    %% AI & Context Service
    subgraph "AI Service"
        direction TB
        AIConn["AIConnectionManager"]:::processing
        TagWS["TagWebSocketManager"]:::processing
    end

    %% API & Auth Layer
    subgraph "API & Auth"
        direction TB
        AuthMgr["AuthManager"]:::auth
        APIClientNode["APIClient"]:::api
        APIConfigNode["APIConfig"]:::api
        ContextAPI["ContextSearchAPI"]:::api
        NotesAPI["NotesAPI"]:::api
        WSClient["WebSocketManager"]:::api
    end

    %% External Services
    subgraph "External Services"
        direction TB
        RESTBackend["Backend REST API"]:::external
        WSBackend["Backend WebSocket"]:::external
    end

    %% Connections
    AppEntry --> SystemMenu
    AppEntry --> SetupView
    AppEntry --> SettingsView
    AppEntry --> AIAssistMgr

    InputMgr -->|shortcut event| WindowCap
    ShortcutDefs --> InputMgr

    WindowCap -->|image+metadata| AIContext
    AIContext -->|sends image| AIConn
    AIConn -->|REST OCR| RESTBackend
    RESTBackend -->|OCR response| AIConn
    AIConn -->|OCR data| AIContext

    AIContext --> AIAssistMgr
    AIContext --> QuickCapture
    AIContext --> ExternalWindowMgr
    AIContext --> AutoContext

    TagWS --> WSBackend
    WSBackend --> TagWS
    TagWS -->|tag updates| AIAssistMgr

    AuthMgr -->|token| APIClientNode
    AuthMgr -.->|token| WSClient

    APIClientNode -->|REST calls| RESTBackend
    APIClientNode --> ContextAPI
    APIClientNode --> NotesAPI
    RESTBackend -->|data| APIClientNode

    WSClient -->|ws| WSBackend
    WSBackend -->|real-time| WSClient

    APIClientNode --> AIAssistMgr
    APIClientNode --> QuickCapture
    APIClientNode --> ExternalWindowMgr

    %% Click Events
    click AIContext "https://github.com/tej-sharma/horizon-overlay/blob/development/Constella Horizon/AI/AIContextManager.swift"
    click AIConn "https://github.com/tej-sharma/horizon-overlay/blob/development/Constella Horizon/AI/AIConnectionManager.swift"
    click TagWS "https://github.com/tej-sharma/horizon-overlay/blob/development/Constella Horizon/AI/TagWebSocketManager.swift"
    click APIClientNode "https://github.com/tej-sharma/horizon-overlay/blob/development/Constella Horizon/API/APIClient.swift"
    click APIConfigNode "https://github.com/tej-sharma/horizon-overlay/blob/development/Constella Horizon/API/APIConfig.swift"
    click ContextAPI "https://github.com/tej-sharma/horizon-overlay/blob/development/Constella Horizon/API/ContextSearchAPI.swift"
    click NotesAPI "https://github.com/tej-sharma/horizon-overlay/blob/development/Constella Horizon/API/NotesAPI.swift"
    click WSClient "https://github.com/tej-sharma/horizon-overlay/blob/development/Constella Horizon/API/WebSocketManager.swift"
    click AuthMgr "https://github.com/tej-sharma/horizon-overlay/blob/development/Constella Horizon/Auth/AuthManager.swift"
    click WindowCap "https://github.com/tej-sharma/horizon-overlay/blob/development/Constella Horizon/ScreenParsing/WindowCaptureManager.swift"
    click InputMgr "https://github.com/tej-sharma/horizon-overlay/blob/development/Constella Horizon/InputEvent/InputEventManager.swift"
    click ShortcutDefs "https://github.com/tej-sharma/horizon-overlay/blob/development/Constella Horizon/InputEvent/Shortcut.swift"
    click AIAssistMgr "https://github.com/tej-sharma/horizon-overlay/blob/development/Constella Horizon/Overlay/AIAssistOverlayManager.swift"
    click AIAssistView "https://github.com/tej-sharma/horizon-overlay/blob/development/Constella Horizon/Overlay/AIAssistView.swift"
    click AIAssistWC "https://github.com/tej-sharma/horizon-overlay/blob/development/Constella Horizon/Overlay/AIAssistWindowController.swift"
    click QuickCapture "https://github.com/tej-sharma/horizon-overlay/blob/development/Constella Horizon/Overlay/QuickCaptureOverlay.swift"
    click ExternalWindowMgr "https://github.com/tej-sharma/horizon-overlay/blob/development/Constella Horizon/Overlay/ExternalWindowOverlayManager.swift"
    click MainView "https://github.com/tej-sharma/horizon-overlay/blob/development/Constella Horizon/Overlay/MainView.swift"
    click MainWindow "https://github.com/tej-sharma/horizon-overlay/blob/development/Constella Horizon/Overlay/MainWindow.swift"
    click AutoContext "https://github.com/tej-sharma/horizon-overlay/blob/development/Constella Horizon/Overlay/AutoContextOverlay.swift"
    click ContextCard "https://github.com/tej-sharma/horizon-overlay/blob/development/Constella Horizon/Overlay/Components/ContextCard.swift"
    click TagChip "https://github.com/tej-sharma/horizon-overlay/blob/development/Constella Horizon/Overlay/Components/TagChip.swift"
    click SystemMenu "https://github.com/tej-sharma/horizon-overlay/blob/development/Constella Horizon/SystemMenu/SystemMenuManager.swift"
    click SetupView "https://github.com/tej-sharma/horizon-overlay/blob/development/Constella Horizon/Setup/SetupView.swift"
    click SetupWC "https://github.com/tej-sharma/horizon-overlay/blob/development/Constella Horizon/Setup/SetupWindowController.swift"
    click WelcomeView "https://github.com/tej-sharma/horizon-overlay/blob/development/Constella Horizon/Setup/WelcomeView.swift"
    click PermissionTemplate "https://github.com/tej-sharma/horizon-overlay/blob/development/Constella Horizon/Setup/PermissionTemplateView.swift"
    click FloatingOnboarding "https://github.com/tej-sharma/horizon-overlay/blob/development/Constella Horizon/Setup/FloatingOnboardingTemplate.swift"
    click PermissionManager "https://github.com/tej-sharma/horizon-overlay/blob/development/Constella Horizon/Setup/PermissionManager.swift"
    click ShortcutTF "https://github.com/tej-sharma/horizon-overlay/blob/development/Constella Horizon/Setup/ShortcutTextField.swift"
    click SettingsView "https://github.com/tej-sharma/horizon-overlay/blob/development/Constella Horizon/Settings/SettingsView.swift"
    click SettingsWC "https://github.com/tej-sharma/horizon-overlay/blob/development/Constella Horizon/Settings/SettingsWindowController.swift"
    click SettingsModel "https://github.com/tej-sharma/horizon-overlay/blob/development/Constella Horizon/Settings/SettingsModel.swift"
    click AppEntry "https://github.com/tej-sharma/horizon-overlay/blob/development/Constella Horizon/ConstellaHorizonApp.swift"

    %% Styles
    classDef ui fill:#D0E8FF,stroke:#333,stroke-width:1px
    classDef processing fill:#D0FFD0,stroke:#333,stroke-width:1px
    classDef api fill:#FFE0B2,stroke:#333,stroke-width:1px
    classDef auth fill:#FFD0B2,stroke:#333,stroke-width:1px
    classDef system fill:#E0E0E0,stroke:#333,stroke-width:1px
    classDef external fill:#F0F0F0,stroke:#333,stroke-width:1px
```
