# znasif/hacktemplate architecture

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

- Interactive diagram: https://gitdiagram.com/znasif/hacktemplate
- Repository: https://github.com/znasif/hacktemplate

## Overview

##### Main Components
- Client Application:
– Components include two variants: the primary client (main.py with screen_capture.py) and a cross-platform beta (main_beta.py with screen_capture_beta.py).
– Responsible for capturing the video feed (note the dual-display requirement) and initiating the stream.
– Establishes the connection (via WebSockets) to the server.
- Server Application:
– The entry point (stream.py) runs as an asynchronous server (using uvicorn) to accept the incoming stream.
– Contains several processing modules under the “processors” folder: base_processor, Groq processor, MediaPipe processor, OCR processor, OpenAI processor, and YOLO processor.
– Additional modules (llama.py and llava.py) likely wrap or interface with more advanced language/vision models.
– Utility scripts (utils.py), and a models directory (which houses for example the YOLO segmentation model, yolo11n-seg.pt).
- External Dependencies and Environment Setup:
- Data Flow:
– Video capture from the client’s monitor is streamed to the server.
– The server processes the stream via the selected processor (user-selected from options such as “Dense Region Caption,” “OCR,” etc.).
– The processed results are then output, with descriptions being read aloud or potentially routed to another system (e.g., WhatsApp desktop app for audio sharing).

##### Interactions and Relationships
– Emphasize that these modules are plugins, making it easy for extension.
- Optionally, include callouts for additional components such as “LLama Module” and “LLava Module” to indicate integration with large language/vision models.

##### Architectural Patterns and Design Principles
- That the application follows a client–server architecture with a separation of concerns:
– The client is solely responsible for capturing video and handling local dependencies.
– The server acts as a processing hub and orchestrates multiple processing pipelines.
- Modular design of the processor components that can be easily swapped or extended based on user selection.
- Asynchronous, event-driven nature of processing (using websockets and uvicorn).

##### Relevant Technologies
- Client with labels for Windows/Cross-Platform differences (indicating pywin32 for Windows, pyautogui/screeninfo for cross-platform).
- Optionally, mention the use of virtual audio cables for routing audio (as part of the remote sharing feature).

##### Specific Elements
– "Client Application" – Include subcomponents "Screen Capture (main.py / screen_capture.py)" and "Cross-Platform Variant (main_beta.py)".
– "Connection Layer" – Indicate the WebSocket link established by the client.
– "Server Application / Stream Handler" – Represented by stream.py.
- Base Processor
- Groq Processor
- MediaPipe Processor
- OCR Processor
- YOLO Processor
- OpenAI Processor
– "LLama/LLava Integration Modules" – Representing advanced model integrations.
- Annotations that indicate configuration points (such as the .env file entries) that enable inter-component communication.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Application
    subgraph "Client Application"
        direction TB
        A1["Primary Client (main.py & screen_capture.py)"]:::client
        A2["Cross-Platform Variant (main_beta.py & screen_capture_beta.py)"]:::client
    end

    %% Connection Layer
    subgraph "Connection and Streaming"
        direction TB
        C1["WebSocket Connection"]:::connection
    end

    %% Server Application
    subgraph "Server Application"
        direction TB
        B1["Stream Handler (stream.py)"]:::server
    end

    %% Processor Modules
    subgraph "Processor Modules"
        direction TB
        P1["Base Processor"]:::processor
        P2["Groq Processor"]:::processor
        P3["MediaPipe Processor"]:::processor
        P4["OCR Processor"]:::processor
        P5["OpenAI Processor"]:::processor
        P6["YOLO Processor"]:::processor
    end

    %% LLama/LLava Integration Modules
    subgraph "LLama/LLava Integration"
        direction TB
        L1["LLama Module"]:::integration
        L2["LLava Module"]:::integration
    end

    %% Models Resource
    subgraph "Models Resource"
        direction TB
        M1["Models Directory"]:::models
        M2["YOLO Segmentation Model"]:::models
    end

    %% External Dependencies
    E1["Environment Setup (environment.yml)"]:::external

    %% Connections: Client to Connection to Server
    A1 -->|"WebSocketStreaming/Data"| C1
    A2 -->|"WebSocketStreaming/Data"| C1
    C1 -->|"DataFeed"| B1

    %% Connections: Server dispatches to Processor Modules and Integration Modules
    B1 -->|"dispatch"| P1
    B1 -->|"dispatch"| P2
    B1 -->|"dispatch"| P3
    B1 -->|"dispatch"| P4
    B1 -->|"dispatch"| P5
    B1 -->|"dispatch"| P6
    B1 -->|"integrate"| L1
    B1 -->|"integrate"| L2

    %% Connection: YOLO Processor uses Models
    P6 -->|"model"| M2

    %% Styles
    classDef client fill:#c2dfff,stroke:#000,stroke-width:2px;
    classDef connection fill:#f0e68c,stroke:#000,stroke-width:2px;
    classDef server fill:#d1ffd6,stroke:#000,stroke-width:2px;
    classDef processor fill:#fff2cc,stroke:#000,stroke-width:2px;
    classDef integration fill:#ead1dc,stroke:#000,stroke-width:2px;
    classDef models fill:#f4cccc,stroke:#000,stroke-width:2px;
    classDef external fill:#d9d2e9,stroke:#000,stroke-width:2px;

    %% Click Events
    click A1 "https://github.com/znasif/hacktemplate/blob/main/client/main.py"
    click A1 "https://github.com/znasif/hacktemplate/blob/main/client/screen_capture.py"
    click A2 "https://github.com/znasif/hacktemplate/blob/main/client/main_beta.py"
    click A2 "https://github.com/znasif/hacktemplate/blob/main/client/screen_capture_beta.py"
    click B1 "https://github.com/znasif/hacktemplate/blob/main/server/stream.py"
    click P1 "https://github.com/znasif/hacktemplate/blob/main/server/processors/base_processor.py"
    click P2 "https://github.com/znasif/hacktemplate/blob/main/server/processors/groq_processor.py"
    click P3 "https://github.com/znasif/hacktemplate/blob/main/server/processors/mediapipe_processor.py"
    click P4 "https://github.com/znasif/hacktemplate/blob/main/server/processors/ocr_processor.py"
    click P5 "https://github.com/znasif/hacktemplate/blob/main/server/processors/openai_processor.py"
    click P6 "https://github.com/znasif/hacktemplate/blob/main/server/processors/yolo_processor.py"
    click L1 "https://github.com/znasif/hacktemplate/blob/main/server/llama.py"
    click L2 "https://github.com/znasif/hacktemplate/blob/main/server/llava.py"
    click M1 "https://github.com/znasif/hacktemplate/tree/main/server/models"
    click M2 "https://github.com/znasif/hacktemplate/blob/main/server/models/yolo11n-seg.pt"
    click E1 "https://github.com/znasif/hacktemplate/blob/main/environment.yml"
```
