# medoedka/videoclusters architecture

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

- Interactive diagram: https://gitdiagram.com/medoedka/videoclusters
- Repository: https://github.com/medoedka/videoclusters

## Overview

##### Project type and purpose
– This is a standalone Python library (“videoclusters”) that exposes clustering algorithms implemented on GPU.
– Primary use case: users import KMeans or Agglomerative classes in their code, push data tensors to CUDA, and retrieve cluster assignments.

##### File structure
– Top‑level:
- requirements.txt → dependency list (PyTorch, etc.)
- src/videoclusters → main package
– Subpackages:
- centroid_based/KMeans.py → the centroid‑based clustering implementation
- HCA/Agglomerative.py → the hierarchical clustering implementation
– No frontend/backend or persistence layers; this is purely a compute library.

##### Extract key technical details from the README
– Uses PyTorch for tensor operations on GPU
– Public API: constructors and fit_predict methods of KMeans and Agglomerative

##### Main components
a. User Application Layer
- “User Code” – any script or notebook that imports and utilizes videoclusters
b. Library Public API
- videoclusters.centroid_based.KMeans
- videoclusters.HCA.Agglomerative
c. Core Computation Modules
- KMeans.fit_predict → internal loops, distance computations, centroid updates
- Agglomerative.fit_predict → linkage matrix computations, cluster merges
d. External Dependencies
- PyTorch tensor library (CPU/GPU)
- CUDA runtime & drivers
e. Data Flow
- Input: torch.Tensor on CUDA device
- Processing: iterative clustering algorithms in Python + CUDA kernels (via PyTorch)
- Output: torch.Tensor of cluster labels

##### Relationships and interactions
– From Public API → Core Computation Modules
– From Modules → PyTorch CUDA Backend
– From PyTorch → GPU hardware
– Finally, back to User Code with result tensor

##### Architectural patterns and design principles
– Modular package structure: each algorithm in its own subpackage
– Single responsibility: classes only implement their clustering logic
– Dependency inversion: relies on PyTorch abstract tensor operations rather than custom C++ kernels

- Algorithm internals in another (e.g., green)
- External dependencies in grey
– Clear labels for methods (fit_predict), data types (torch.Tensor), and packages

##### Detailed breakdown
Layer 1: User Application
[User Code / Notebook]
↓ import & call
Layer 2: Public API
[videoclusters.centroid_based.KMeans]
[videoclusters.HCA.Agglomerative]
↓ internally invoke
Layer 3: Core Modules
[KMeans.fit_predict logic]
[Agglomerative.fit_predict logic]
↓ tensor ops via
Layer 4: Framework & Hardware
[PyTorch CUDA Backend] → [GPU Hardware]

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Layer 1: User Application
    subgraph "Layer 1: User Application"
        UserCode["User Code / Notebook"]:::external
    end

    %% Layer 2: Public API
    subgraph "Layer 2: Public API"
        package_root["videoclusters Package Root"]:::api
        centroid_based_init["centroid_based Subpackage"]:::api
        KMeans["videoclusters.centroid_based.KMeans"]:::api
        hca_init["HCA Subpackage"]:::api
        Agglomerative["videoclusters.HCA.Agglomerative"]:::api
        NewAlgorithm["+ NewAlgorithm"]:::api
    end

    %% Layer 3: Core Modules
    subgraph "Layer 3: Core Computation Modules"
        KMeansLogic["KMeans.fit_predict Logic"]:::internals
        AggLogic["Agglomerative.fit_predict Logic"]:::internals
    end

    %% Layer 4: Framework & Hardware
    subgraph "Layer 4: Framework & Hardware"
        PyTorch["PyTorch CUDA Backend"]:::external
        GPU["GPU Hardware"]:::hardware
    end

    %% Data Flow
    UserCode -->|"import & call"| KMeans
    UserCode -->|"import & call"| Agglomerative

    KMeans -->|"calls fit_predict"| KMeansLogic
    Agglomerative -->|"calls fit_predict"| AggLogic

    KMeansLogic -->|"tensor ops via"| PyTorch
    AggLogic -->|"tensor ops via"| PyTorch

    PyTorch -->|"dispatch to"| GPU
    GPU -->|"returns results"| UserCode

    %% Project Files & Metadata
    subgraph "Project Files"
        requirements["requirements.txt"]:::external
        README["README.md"]:::external
        LICENSE["LICENSE.txt"]:::external
    end

    %% Click Events
    click package_root "https://github.com/medoedka/videoclusters/blob/main/src/videoclusters/__init__.py"
    click centroid_based_init "https://github.com/medoedka/videoclusters/blob/main/src/videoclusters/centroid_based/__init__.py"
    click KMeans "https://github.com/medoedka/videoclusters/blob/main/src/videoclusters/centroid_based/KMeans.py"
    click hca_init "https://github.com/medoedka/videoclusters/blob/main/src/videoclusters/HCA/__init__.py"
    click Agglomerative "https://github.com/medoedka/videoclusters/blob/main/src/videoclusters/HCA/Agglomerative.py"
    click requirements "https://github.com/medoedka/videoclusters/blob/main/requirements.txt"
    click README "https://github.com/medoedka/videoclusters/blob/main/README.md"
    click LICENSE "https://github.com/medoedka/videoclusters/blob/main/LICENSE.txt"

    %% Styles
    classDef api fill:#D0E8FF,stroke:#0366d6,color:#0366d6;
    classDef internals fill:#E6FFDC,stroke:#22863a,color:#22863a;
    classDef external fill:#F0F0F0,stroke:#586069,color:#586069;
    classDef hardware fill:#FFF5B1,stroke:#D73A49,color:#D73A49;
```
