# gulkoa/uncountable architecture

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

- Interactive diagram: https://gitdiagram.com/gulkoa/uncountable
- Repository: https://github.com/gulkoa/uncountable

## Overview

##### Main Components
- Main Electron.js Process – This is the central orchestration component. It is responsible for:
- Spawning and managing Python child processes for running object detection.
- Handling runtime configurations and driving communication between the UI and backend.
- Renderer Electron.js Process (Frontend) – This component is focused on the end-user experience by:
- Displaying real-time video feeds with overlaid tracking information.
- Providing UI controls for configuration and alert monitoring.
- Python Object Detection Module – A backend service implemented in Python that:
- Runs a fine-tuned YOLOv8 model (using PyTorch) to detect surgical instruments.
- Uses Websockets for real-time data transmission back to the Electron processes.
- Data and Resources – Include components for:
- The custom dataset (under the “images” directory) used to train and refine the model.
- Pre-trained model files such as “yolov8m-seg.pt”, “best2.pt”, “best4.pt”, etc.
- Additional scripts (e.g. generateData.py, generateBackgroundImages.py) for data preparation.

##### Relationships and Interactions
- The Main Electron Process launches the Python object detection service and then manages bidirectional communication between:
- The Python processes (handling heavy computer vision operations).
- The Renderer process (user interface) which displays the video stream and alerts.
- The Python module (object detection module) works with a YOLOv8 model under the “python/ultralytics” folder structure. The training/inference code and utility scripts here are critical, with dependencies on PyTorch.
- Communication is handled via Websockets, ensuring low-latency transmission of detection results between the processes.

##### Important Architectural Patterns and Design Principles
- Separation of Concerns – Distinct processes are used to isolate the UI (renderer) from the backend (object detection), ensuring that intensive computations do not block the user interface.
- Child Process Management – The main Electron process handles Python child processes for executing deep learning tasks.
- Real-Time Communication – Use of Websockets for continuous, real-time data flow between components.
- Modular Design – The Python source is organized into modular subdirectories (ultralytics/engine, models, nn, trackers, etc.) reflecting a clear separation between object detection, tracking, and utility functions.

##### Relevant Technologies and Tools
- Electron.js (both main and renderer processes, leveraging Node.js and web technologies like HTML, CSS, and JavaScript).
- Python 3.8+ with key dependencies (PyTorch, YOLOv8 configurations and inference scripts).
- Websockets for communication between the Electron process and Python child processes.
- Data resources including custom images and pre-trained model files.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Electron Application Subgraph
    subgraph "Electron Application"
        MAIN["Electron Main Process"]:::electronMain
        RENDERER["Electron Renderer Process (Frontend)"]:::electronRenderer
    end

    %% Python Object Detection Module
    PYTHON["Python Object Detection (YOLOv8/PyTorch)"]:::pythonModule

    %% Data and Resources Subgraph
    subgraph "Data and Resources"
        DATASET["Custom Dataset"]:::dataResource
        MODELS["Pre-trained Models"]:::dataResource
        SCRIPTS["Data Preparation Scripts"]:::dataResource
    end

    %% Communication arrows between nodes
    RENDERER -->|"sends commands/config"| MAIN
    MAIN -->|"spawns detection process via Websockets"| PYTHON
    PYTHON -->|"sends real-time detection outputs"| RENDERER

    %% Arrows to Data and Resources
    PYTHON ---|"accesses"| DATASET
    PYTHON ---|"loads"| MODELS
    PYTHON ---|"utilizes"| SCRIPTS

    %% Click Events
    click MAIN "https://github.com/gulkoa/uncountable/blob/main/client/main.js"
    click RENDERER "https://github.com/gulkoa/uncountable/blob/main/client/renderer.js"
    click RENDERER "https://github.com/gulkoa/uncountable/blob/main/client/index.html"
    click PYTHON "https://github.com/gulkoa/uncountable/blob/main/python/server.py"
    click PYTHON "https://github.com/gulkoa/uncountable/blob/main/python/flask_server.py"
    click PYTHON "https://github.com/gulkoa/uncountable/blob/main/python/yolo_demo.py"
    click DATASET "https://github.com/gulkoa/uncountable/tree/main/images/"
    click MODELS "https://github.com/gulkoa/uncountable/blob/main/client/best2.pt"
    click MODELS "https://github.com/gulkoa/uncountable/blob/main/client/best4.pt"
    click MODELS "https://github.com/gulkoa/uncountable/blob/main/client/yolov8m-seg.pt"
    click SCRIPTS "https://github.com/gulkoa/uncountable/blob/main/generateData.py"
    click SCRIPTS "https://github.com/gulkoa/uncountable/blob/main/generateBackgroundImages.py"

    %% Styles
    classDef electronMain fill:#FFCC80,stroke:#BF360C,stroke-width:2px;
    classDef electronRenderer fill:#90CAF9,stroke:#0D47A1,stroke-width:2px;
    classDef pythonModule fill:#A5D6A7,stroke:#1B5E20,stroke-width:2px;
    classDef dataResource fill:#E0E0E0,stroke:#616161,stroke-width:2px;
```
