# yaak-ai/rbyte architecture

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

- Interactive diagram: https://gitdiagram.com/yaak-ai/rbyte
- Repository: https://github.com/yaak-ai/rbyte

## Overview

##### Main Components
- Data Input/IO Modules:
- These are located in the src/rbyte/io directory. Each submodule (_json, _mcap, _numpy, hdf5, path, rrd, video, yaak) is dedicated to reading a specific data format.
- Their primary role is building data frames from raw inputs using a builder pattern. For example, each format has its own dataframe_builder script.
- Core Dataset Logic:
- At the core is the PyTorch Dataset implementation (see src/rbyte/dataset.py). It wraps the multimodal data into tensorclass samples which are then ready for consumption by machine learning pipelines.
- Configuration and Templates:
- The config directory contains YAML templates (for dataloader, dataset, logger configurations, and even visualization) that govern how data is loaded, processed, and logged.
- Visualization and Logging:
- Utility Components:
- The src/rbyte/utils folder holds helper functions and decoders (especially for MCAP files) that assist in the transformation and processing of data.
- Testing and Example Use Cases:
- The tests directory features several tests ensuring that data frame creation, dataloader, dataset functionalities, and even examples are working as expected.
- The examples folder provides jupyter notebooks (for instance, examples/nuscenes_mcap.ipynb) that demonstrate how to execute and interact with the system.

##### Their Relationships and Interactions
- Data Input Modules fetch raw multi-format data; each IO module (JSON, MCAP, etc.) processes its input using a corresponding dataframe_builder.
- The processed data is then passed into the PyTorch Dataset, effectively wrapping it as tensorclass samples.
- Utilities support both IO processing (e.g., decoders) and dataset operations, bridging any gaps between raw input and processed data, ensuring consistency and robustness.

##### Architectural Patterns and Design Principles
- Modularity: Each data format and functionality (configuration, visualization, logging) is encapsulated in its own module.
- Separation of Concerns: Data ingestion, processing, and visualization are distinctly separated. For example, IO modules specialize in data transformation while dataset modules integrate data for PyTorch.
- Builder Pattern: Used extensively in the various dataframe_builder scripts to transform raw data into structured formats.
- Configurability: The project leverages YAML configuration templates to allow flexible adjustments in data loading, logging, and visualization settings.

##### Detail the Technologies, Frameworks, and Libraries
- PyTorch: Central to providing the Dataset structure.
- tensorclass: Utilized to encapsulate samples as tensor objects.
- YAML: For configuration templates which describe various settings (dataloader, logger, visualization).
- Jupyter Notebooks: Present in the examples, used to illustrate practical usage of the library.
- Additional tools: Scripts like justfile and tools such as uv, just, and ytt are part of the development and execution pipeline.

## Diagram (Mermaid)

```mermaid
graph TD
    %% Configuration Node
    Config["Configuration (YAML Templates)"]:::config

    %% Data Input Modules Subgraph
    subgraph "Data Input Modules"
        IO1["JSON IO - DataFrame Builder"]:::io
        IO2["MCAP IO - DataFrame Builder"]:::io
        IO3["MCAP IO - Tensor Source"]:::io
        IO4["NumPy IO - Tensor Source"]:::io
        IO5["HDF5 IO - DataFrame Builder"]:::io
        IO6["HDF5 IO - Tensor Source"]:::io
        IO7["Path IO - DataFrame Builder"]:::io
        IO8["Path IO - Tensor Source"]:::io
        IO9["RRD IO - DataFrame Builder"]:::io
        IO10["RRD IO - Frame Source"]:::io
        IO11["Video IO - DataFrame Builder"]:::io
        IO12["Video IO - FFmpeg Source"]:::io
        IO13["Video IO - Vali Source"]:::io
        IO14["YAak IO - DataFrame Builder"]:::io
    end

    %% Aggregated Output Node
    DFOutput["DataFrame Output"]:::io

    %% Core Dataset Node
    Dataset["Dataset (PyTorch & tensorclass)"]:::dataset

    %% Visualization & Logging Subgraph
    subgraph "Visualization & Logging"
        Viz1["Console Logger"]:::viz
        Viz2["Rerun Logger"]:::viz
        Viz3["Visualize Script"]:::viz
    end

    %% Utility Components Node
    Utils["Utils (Decoders & Helpers)"]:::utils

    %% Testing & Examples Node
    TestExp["Tests & Examples"]:::test

    %% Connections

    %% Configuration influences Data Input and Visualization layers
    Config -->|"configures"| DFOutput
    Config -->|"configures"| Viz1
    Config -->|"configures"| Viz2
    Config -->|"configures"| Viz3

    %% IO Modules feed into DataFrame Output
    IO1 --> DFOutput
    IO2 --> DFOutput
    IO3 --> DFOutput
    IO4 --> DFOutput
    IO5 --> DFOutput
    IO6 --> DFOutput
    IO7 --> DFOutput
    IO8 --> DFOutput
    IO9 --> DFOutput
    IO10 --> DFOutput
    IO11 --> DFOutput
    IO12 --> DFOutput
    IO13 --> DFOutput
    IO14 --> DFOutput

    %% Utility supports the data output and dataset processing
    Utils -.-> DFOutput
    Utils -.-> Dataset

    %% Data flows from DataFrame Output to the Core Dataset
    DFOutput --> Dataset

    %% Core Dataset routes processed data to visualization and logging
    Dataset --> Viz1
    Dataset --> Viz2
    Dataset --> Viz3

    %% Testing and Examples exercise the core dataset and visualization
    TestExp --> Dataset
    TestExp --> Viz3

    %% Styling Classes
    classDef config fill:#f9c74f,stroke:#333,stroke-width:2px,color:#000;
    classDef io fill:#90be6d,stroke:#333,stroke-width:2px,color:#000;
    classDef dataset fill:#f94144,stroke:#333,stroke-width:2px,color:#fff;
    classDef viz fill:#577590,stroke:#333,stroke-width:2px,color:#fff;
    classDef utils fill:#277da1,stroke:#333,stroke-width:2px,color:#fff;
    classDef test fill:#f3722c,stroke:#333,stroke-width:2px,color:#000;

    %% Click Events
    click IO1 "https://github.com/yaak-ai/rbyte/blob/main/src/rbyte/io/_json/dataframe_builder.py"
    click IO2 "https://github.com/yaak-ai/rbyte/blob/main/src/rbyte/io/_mcap/dataframe_builder.py"
    click IO3 "https://github.com/yaak-ai/rbyte/blob/main/src/rbyte/io/_mcap/tensor_source.py"
    click IO4 "https://github.com/yaak-ai/rbyte/blob/main/src/rbyte/io/_numpy/tensor_source.py"
    click IO5 "https://github.com/yaak-ai/rbyte/blob/main/src/rbyte/io/hdf5/dataframe_builder.py"
    click IO6 "https://github.com/yaak-ai/rbyte/blob/main/src/rbyte/io/hdf5/tensor_source.py"
    click IO7 "https://github.com/yaak-ai/rbyte/blob/main/src/rbyte/io/path/dataframe_builder.py"
    click IO8 "https://github.com/yaak-ai/rbyte/blob/main/src/rbyte/io/path/tensor_source.py"
    click IO9 "https://github.com/yaak-ai/rbyte/blob/main/src/rbyte/io/rrd/dataframe_builder.py"
    click IO10 "https://github.com/yaak-ai/rbyte/blob/main/src/rbyte/io/rrd/frame_source.py"
    click IO11 "https://github.com/yaak-ai/rbyte/blob/main/src/rbyte/io/video/dataframe_builder.py"
    click IO12 "https://github.com/yaak-ai/rbyte/blob/main/src/rbyte/io/video/ffmpeg_source.py"
    click IO13 "https://github.com/yaak-ai/rbyte/blob/main/src/rbyte/io/video/vali_source.py"
    click IO14 "https://github.com/yaak-ai/rbyte/blob/main/src/rbyte/io/yaak/metadata/dataframe_builder.py"
    click Dataset "https://github.com/yaak-ai/rbyte/blob/main/src/rbyte/dataset.py"
    click Config "https://github.com/yaak-ai/rbyte/tree/main/config/_templates"
    click Viz1 "https://github.com/yaak-ai/rbyte/blob/main/src/rbyte/viz/loggers/console_logger.py"
    click Viz2 "https://github.com/yaak-ai/rbyte/blob/main/src/rbyte/viz/loggers/rerun_logger.py"
    click Viz3 "https://github.com/yaak-ai/rbyte/blob/main/src/rbyte/scripts/visualize.py"
    click Utils "https://github.com/yaak-ai/rbyte/tree/main/src/rbyte/utils"
    click TestExp "https://github.com/yaak-ai/rbyte/tree/main/tests"
```
