# hukenovs/slovo architecture

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

- Interactive diagram: https://gitdiagram.com/hukenovs/slovo
- Repository: https://github.com/hukenovs/slovo

## Overview

##### Main Components
- Data Repository – Represent the Slovo dataset as a primary component. This includes the raw video files (both trimmed and original), the annotation files (like the CSV that holds metadata and timestamps), and additional annotations such as the MediaPipe landmarks JSON.
- Configuration & Constants – Include the config_example.yaml and constants.py files. These indicate that system parameters and constants are defined in a dedicated module, which the demo and possibly other scripts use.
- Demo / Inference Pipeline – The demo.py script is the entry point for running inference. It is responsible for reading the configuration, possibly setting up multi-processing (via the --mp flag), and handling the prediction request.
- Example Notebooks – The examples directory contains Jupyter notebooks that demonstrate how to perform tasks like video processing, visualizing landmarks, and possibly running the models. These serve as usage examples and testing modules.
- License and Documentation – Although not a processing component, showing a documentation module (README, licenses in the license folder) is valuable to indicate that the project is well-documented and contains multiple usage instructions and citations.

##### Relationships and Data Flow
- The Model Inference Engine block stands as the center of the pipeline: it loads one of the pre-trained models (with ONNX or TorchScript weights) based on configuration and then processes the pre-processed video inputs.
- The Demo and Example Notebooks blocks then interact with the Inference Engine. For example, demo.py uses command line parameters to initialize the configuration, read input video data, process it through the model, and then provide output (such as predictions showcased in the demo.gif found in the images folder).
– Data Repository → Pre-processing/Annotation Parser
– Pre-processing Module → Model Inference Engine
– Configuration/Constants → Demo Script & Model Inference Engine (they both depend on configuration settings)
– Inference Engine → Demo/Visualization Interface (demo.py and notebooks display results).

##### Architectural Patterns and Technologies
- Although the project is not an enterprise web app, it still exhibits a modular design. Modules are clearly separated: one for configuration, one for data and pre-processing, and one for model inference/demonstration.
- “plug-and-play” nature of pre-trained models (multiple architectures available) which benefits from uniform interfaces in demo.py.
- The use of command-line flags in demo.py (like --mp for multiprocessing) shows that the pipeline is designed with performance/scalability in mind although on a prototype scale.
- Mention that libraries such as ONNX and TorchScript are integral since they encapsulate the models and are delivered as weights. Their presence should be captured within the Model Inference Engine component.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Data & Preprocessing"
        A["Data Repository (raw videos, annotations)"]:::data
        B["Pre-processing/Annotation Parser"]:::processing
    end

    subgraph "Configuration"
        C1["config_example.yaml"]:::config
        C2["constants.py"]:::config
    end

    subgraph "Inference Engine"
        D["Model Inference Engine (Baseline Models: ONNX, TorchScript)"]:::processing
    end

    subgraph "Demo & Visualization"
        E1["demo.py"]:::processing
        E2["Example Notebooks"]:::processing
    end

    subgraph "Documentation"
        F1["README.md"]:::doc
        F2["License Directory"]:::doc
    end

    A -->|"feeds"| B
    C1 -->|"config_params"| B
    C2 -->|"config_params"| B
    B -->|"processed_data"| D
    C1 -->|"config_params"| D
    C2 -->|"config_params"| D
    D -->|"predictions"| E1
    D -->|"predictions"| E2

    click A "https://github.com/hukenovs/slovo/tree/main/examples"
    click C1 "https://github.com/hukenovs/slovo/blob/main/config_example.yaml"
    click C2 "https://github.com/hukenovs/slovo/blob/main/constants.py"
    click E1 "https://github.com/hukenovs/slovo/blob/main/demo.py"
    click E2 "https://github.com/hukenovs/slovo/tree/main/examples"
    click F1 "https://github.com/hukenovs/slovo/blob/main/README.md"
    click F2 "https://github.com/hukenovs/slovo/tree/main/license"

    classDef data fill:#FFE4B5,stroke:#000,stroke-width:2px;
    classDef processing fill:#ADD8E6,stroke:#000,stroke-width:2px;
    classDef config fill:#90EE90,stroke:#000,stroke-width:2px;
    classDef doc fill:#D3D3D3,stroke:#000,stroke-width:2px;
```
