# omniflix/omniflixhub architecture

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

- Interactive diagram: https://gitdiagram.com/omniflix/omniflixhub
- Repository: https://github.com/omniflix/omniflixhub

## Overview

Based on our analysis of the file tree and README, OmniFlix Hub is a blockchain application built on top of Cosmos-SDK and CometBFT (formerly Tendermint). Its purpose is to serve as the root chain for the OmniFlix Network, managing NFT-related operations, marketplace activities, and various specialized modules (such as ITC, onft, tokenfactory, globalfee, etc.). The project is clearly structured as a modular blockchain application with multiple components that interact with the core consensus engine.

##### Main Components
- Blockchain Client/Node: In the “cmd/omniflixhubd” directory, the main executable is initialized here. This component stands for the node process that hooks the blockchain state machine to the underlying CometBFT consensus layer.
- Core Application Layer: The “app” directory contains the core logic of the blockchain, including state initialization (genesis), upgrade handlers, parameter encoding, and more.
- Modular Business Logic: The “x” directory holds many of the blockchain’s domain-specific modules:
- Alloc (allocation)
- Globalfee (handling fee policies)
- ITC (Interchain or specific token/campaign functionality)
- Marketplace (handling auctions, listings, bids, etc.)
- Onft (NFT functionality)
- Tokenfactory (denom creation and custom logic around tokens)
- API and Client Interfaces: Some modules such as “openapiconsole” (in the app folder) and the CLI subdirectories in “x” and “cmd” indicate the provision of REST APIs and command-line interactions.
- Protobuf Definitions: The “proto” directory defines the service interfaces, messages, and gRPC/REST contracts which are crucial for both internal module communication and external integration.
- CI/CD and Build Infrastructure: The presence of GitHub workflows (.github/workflows) along with Makefile and scripts reflect the overall infrastructure concerning build, lint, tests, releases, and documentation generation.

##### Relationships and Interactions
- The CLI/API front-end (via “cmd/omniflixhubd” and client directories inside “x”) interacts with the core node.
- Data flows from external requests (via REST endpoints or command-line commands) into the node application.
- The node application routes the request to specific modules within the business logic layer as per the Cosmos-SDK patterns.
- Each module (alloc, globalfee, itc, marketplace, onft, tokenfactory) is responsible for handling domain-specific transactions, maintaining their custom state in the multi-store repository.
- Underneath this, the CometBFT consensus engine coordinates block production, network validation, and state finality.

##### Architectural Patterns and Design Principles
- Modularity: The design clearly follows the Cosmos-SDK’s modular architecture. Each submodule in “x” is designed to encapsulate distinct features and can be developed, tested, and upgraded independently.
- Separation of Concerns: The project separates the node’s command logic (cmd/), core business logic (app/), and domain-specific modules (x/). Also, the API and proto files are in dedicated directories.
- Upgradability: There is a dedicated “upgrades” structure in the “app” folder showing multiple blocks for performing versioned upgrades efficiently.
- Code Generation and Protocol Buffers: The “proto” directory indicates that code generation (with buf or similar tools) plays a central role in keeping client and server contracts in sync.

##### Relevant Technologies, Frameworks, and Libraries
- Cosmos-SDK for blockchain development
- CometBFT (Tendermint-based consensus mechanism)
- Go programming language (Go modules, Makefile for build management)
- Protobuf/gRPC mechanisms for API definitions
- CI/CD using GitHub workflows and various shell scripts for automation

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "External Layer"
        A["CLI/API Interfaces"]:::external
    end

    subgraph "Node/Execution Environment"
        B["Blockchain Client (omniflixhubd)"]:::node
        C["Core Application (app)"]:::node
    end

    subgraph "Business Logic Modules"
        D["Module: Alloc"]:::module
        E["Module: Globalfee"]:::module
        F["Module: ITC"]:::module
        G["Module: Marketplace"]:::module
        H["Module: Onft"]:::module
        I["Module: Tokenfactory"]:::module
    end

    subgraph "Consensus Layer"
        J["Consensus Engine (CometBFT)"]:::consensus
    end

    K["Protobuf Definitions (proto)"]:::proto

    subgraph "Infrastructure"
        L["CI/CD (.github/workflows)"]:::infra
        M["Makefile"]:::infra
    end

    %% Data Flow
    A -->|"calls"| B
    B -->|"initializes"| C
    C -->|"routes_tx"| D
    C -->|"routes_tx"| E
    C -->|"routes_tx"| F
    C -->|"routes_tx"| G
    C -->|"routes_tx"| H
    C -->|"routes_tx"| I

    D -->|"state_update"| J
    E -->|"state_update"| J
    F -->|"state_update"| J
    G -->|"state_update"| J
    H -->|"state_update"| J
    I -->|"state_update"| J

    K -- "defines_contracts" --> C
    K -- "defines_contracts" --> D
    K -- "defines_contracts" --> E
    K -- "defines_contracts" --> F
    K -- "defines_contracts" --> G
    K -- "defines_contracts" --> H
    K -- "defines_contracts" --> I

    L ---|"supports_build"| B
    M ---|"supports_build"| B

    %% Click Events
    click B "https://github.com/omniflix/omniflixhub/tree/main/cmd/omniflixhubd"
    click C "https://github.com/omniflix/omniflixhub/tree/main/app"
    click D "https://github.com/omniflix/omniflixhub/tree/main/x/alloc"
    click E "https://github.com/omniflix/omniflixhub/tree/main/x/globalfee"
    click F "https://github.com/omniflix/omniflixhub/tree/main/x/itc"
    click G "https://github.com/omniflix/omniflixhub/tree/main/x/marketplace"
    click H "https://github.com/omniflix/omniflixhub/tree/main/x/onft"
    click I "https://github.com/omniflix/omniflixhub/tree/main/x/tokenfactory"
    click A "https://github.com/omniflix/omniflixhub/tree/main/app/openapiconsole"
    click K "https://github.com/omniflix/omniflixhub/tree/main/proto"
    click L "https://github.com/omniflix/omniflixhub/tree/main/.github/workflows"
    click M "https://github.com/omniflix/omniflixhub/tree/main/Makefile"

    %% Styles
    classDef external fill:#ffd700,stroke:#333,stroke-width:2px;
    classDef node fill:#8fbc8f,stroke:#333,stroke-width:2px;
    classDef module fill:#add8e6,stroke:#333,stroke-width:2px;
    classDef consensus fill:#ff7f50,stroke:#333,stroke-width:2px;
    classDef proto fill:#daa520,stroke:#333,stroke-width:2px;
    classDef infra fill:#d3d3d3,stroke:#333,stroke-width:2px;
```
