# danhdoan/intel-gaudi-lab architecture

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

- Interactive diagram: https://gitdiagram.com/danhdoan/intel-gaudi-lab
- Repository: https://github.com/danhdoan/intel-gaudi-lab

## Overview

##### Main Components
- Docker/Container Environment: Represented by the Docker-related files (compose.yml, example.env, Makefile targets like “up”, “connect”, “down”). This component handles the development environment setup (especially for the habana_frameworks service).
- Application Entry Point: The “apps” directory (especially apps/app.py) likely contains the main application logic that gets executed.
- Experimentals: The “experimentals” directory contains scripts (e.g., inference_stable_diffusion.py, stable_diffusion_2_1_app.py, run.sh) which seem to be used for testing new inference methods, likely integrating with Intel Gaudi.
- Libraries (libs): This directory is key as it aggregates reusable functionality:
- CLI Parsing (libs/cli/cli_parser.py) — command-line interface for user interactions.
- Configurations (libs/configs/configs.py) — for managing environment and application configuration.
- Utilities (libs/utils), including logging, time, and averaging functionalities, which play supporting roles throughout the codebase.
- Public Assets: The “public” folder stores static assets (index.html, script.js, styles.css) that may serve as the front end or dashboard for interacting with the AI experiments.
- Setup and Dependency Management: Files such as requirements.txt, setup.py, pyproject.toml indicate Python packaging and dependency resolution, which are important for both development and deployment.

##### Relationships and Interactions
- Experimentals as Extensions: The experimentals directory, which includes scripts for running stable diffusion experiments, interacts with both the core application and the underlying libraries. It might either run as separate processes or be triggered via the CLI.
- Public Frontend: If the front end (in public) is involved (perhaps for visualization or dashboards), show a connection between the frontend and the application backend.
- Dependency/Configuration Flow: Include how Makefile and scripts (like scripts/source_env.sh) manage configuration and prepare the development environment.

##### Architectural Patterns & Design Principles
- Modular Design: The clear separation into apps, libs, experimentals, and public directories suggests a modular architecture. Each module has well-defined roles.
- Containerization: The use of Docker (compose.yml, example.env, and Makefile commands) emphasizes container-based deployment and isolation.
- Extensibility: The structure in “libs” to handle CLI, configuration management, and utilities suggests that the codebase was designed for reusability and ease of extension for various experiments.

##### Elements
- Use clear labels for each component with names (e.g., “Docker Environment”, “Application Core (apps/app.py)”, “CLI & Config Utils”, “Experiment Scripts”, “Static Frontend”).
- Deployment configuration details such as the Docker container layer if useful, and annotate infrastructure concerns (like the Makefile and environment setup via scripts).

##### Final Detailed Outline
- Top Layer: Deployment & Environment Management
- Docker Container (with compose.yml & Makefile commands)
- Virtual Environment Management (scripts/source_env.sh, requirements.txt, pyproject.toml)
- Mid Layer: Application Core
- Main Application (apps/app.py)
- Libraries (libs) divided into:
- CLI (libs/cli)
- Config Managers (libs/configs)
- Utility Modules (libs/utils, logger_utils, time_utils, averager)
- Side/Extension Layer: Experiment Modules
- Experiment Scripts (experimentals folder)
- Connections (integration with the main app or libraries)
- Frontend Interface (Public Assets)
- Static Web Assets (index.html, script.js, styles.css)
- Interaction with the application if applicable (e.g., for visualization).

This approach will provide a comprehensive, accurate visual representation of the project's architecture tailored to its purpose as a platform for AI experiments with Intel Gaudi.

## Diagram (Mermaid)

```mermaid
graph TD
    %% Deployment & Environment Management
    subgraph "Deployment & Environment Management"
        subgraph "Container Environment"
            compose("Docker Compose File"):::docker
            env("Env File"):::docker
            makefile("Makefile"):::docker
            sourceenv("Env Setup Script"):::docker
        end
        subgraph "Dependency Setup"
            req("requirements.txt"):::dep
            setup("setup.py"):::dep
            pyproj("pyproject.toml"):::dep
        end
    end

    %% Application Core and Libraries
    subgraph "Application Core"
        app("Application Core (apps/app.py)"):::app
        subgraph "Libraries"
            cli("CLI Parsing (libs/cli/cli_parser.py)"):::lib
            config("Config Management (libs/configs/configs.py)"):::lib
            common("Common Utility (libs/utils/common.py)"):::lib
            logger("Logger Utilities (libs/utils/logger_utils.py)"):::lib
            timeu("Time Utilities (libs/utils/time_utils.py)"):::lib
            averager("Averager (libs/utils/averager/averager.py)"):::lib
        end
    end

    %% Experiment Modules
    subgraph "Experiment Modules"
        exp1("Stable Diffusion Inference (experimentals/inference_stable_diffusion.py)"):::experiment
        exp2("Stable Diffusion 2.1 App (experimentals/stable_diffusion_2_1_app.py)"):::experiment
        exp3("Experiment Run Script (experimentals/run.sh)"):::experiment
    end

    %% Public Frontend
    subgraph "Public Frontend"
        html("HTML File (public/index.html)"):::frontend
        js("JS File (public/script.js)"):::frontend
        css("CSS File (public/assets/styles.css)"):::frontend
    end

    %% Connections from Deployment to Application Core
    compose -->|"runs"| app
    env -->|"configures"| app
    makefile -->|"triggers"| app
    sourceenv -->|"sets up"| app
    req --> app
    setup --> app
    pyproj --> app

    %% Application Core uses Libraries
    app -->|"uses"| cli
    app -->|"uses"| config
    app -->|"uses"| common
    app -->|"uses"| logger
    app -->|"uses"| timeu
    app -->|"uses"| averager

    %% Experiment Modules interact with Application Core and Libraries
    exp1 -->|"triggers"| app
    exp2 -->|"triggers"| app
    exp3 -->|"triggers"| app
    exp1 -->|"leverages"| config
    exp2 -->|"leverages"| config
    exp1 -->|"uses"| common
    exp2 -->|"uses"| common

    %% Public Frontend interacts with Application Core
    html -->|"interfaces"| app
    js -->|"interfaces"| app
    css -->|"interfaces"| app

    %% Click Events for Deployment & Environment Management
    click compose "https://github.com/danhdoan/intel-gaudi-lab/blob/main/compose.yml"
    click env "https://github.com/danhdoan/intel-gaudi-lab/blob/main/example.env"
    click makefile "https://github.com/danhdoan/intel-gaudi-lab/tree/main/Makefile"
    click sourceenv "https://github.com/danhdoan/intel-gaudi-lab/blob/main/scripts/source_env.sh"
    click req "https://github.com/danhdoan/intel-gaudi-lab/blob/main/requirements.txt"
    click setup "https://github.com/danhdoan/intel-gaudi-lab/blob/main/setup.py"
    click pyproj "https://github.com/danhdoan/intel-gaudi-lab/blob/main/pyproject.toml"

    %% Click Event for Application Entry
    click app "https://github.com/danhdoan/intel-gaudi-lab/blob/main/apps/app.py"

    %% Click Events for Libraries
    click cli "https://github.com/danhdoan/intel-gaudi-lab/blob/main/libs/cli/cli_parser.py"
    click config "https://github.com/danhdoan/intel-gaudi-lab/blob/main/libs/configs/configs.py"
    click common "https://github.com/danhdoan/intel-gaudi-lab/blob/main/libs/utils/common.py"
    click logger "https://github.com/danhdoan/intel-gaudi-lab/blob/main/libs/utils/logger_utils.py"
    click timeu "https://github.com/danhdoan/intel-gaudi-lab/blob/main/libs/utils/time_utils.py"
    click averager "https://github.com/danhdoan/intel-gaudi-lab/blob/main/libs/utils/averager/averager.py"

    %% Click Events for Experiment Modules
    click exp1 "https://github.com/danhdoan/intel-gaudi-lab/blob/main/experimentals/inference_stable_diffusion.py"
    click exp2 "https://github.com/danhdoan/intel-gaudi-lab/blob/main/experimentals/stable_diffusion_2_1_app.py"
    click exp3 "https://github.com/danhdoan/intel-gaudi-lab/blob/main/experimentals/run.sh"

    %% Click Events for Public Frontend Assets
    click html "https://github.com/danhdoan/intel-gaudi-lab/blob/main/public/index.html"
    click js "https://github.com/danhdoan/intel-gaudi-lab/blob/main/public/script.js"
    click css "https://github.com/danhdoan/intel-gaudi-lab/blob/main/public/assets/styles.css"

    %% Styles
    classDef docker fill:#fdd,stroke:#900,stroke-width:2px;
    classDef dep fill:#dfd,stroke:#090,stroke-width:2px;
    classDef app fill:#ddf,stroke:#009,stroke-width:2px;
    classDef lib fill:#ffd,stroke:#990,stroke-width:2px;
    classDef experiment fill:#fdf,stroke:#909,stroke-width:2px;
    classDef frontend fill:#cff,stroke:#099,stroke-width:2px;
```
