# akash-network/provider architecture

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

- Interactive diagram: https://gitdiagram.com/akash-network/provider
- Repository: https://github.com/akash-network/provider

## Overview

##### Key Project Components
- Bid Engine (bidengine folder): This component is responsible for handling on-chain orders and determining bid placement according to dynamic pricing. Indicate that it listens for changes in configuration and triggers bids.
- Cluster Management (cluster folder): This is the interface to the compute clusters (mainly Kubernetes here). It includes many submodules such as kube-specific factories, builders, and operators that handle deployments, clean-ups, and resource management.
- Command-line Interface (cmd folder): Uses the “cobra” framework to bootstrap the daemon and wire up the different services. It acts as an entry point to start the daemon.
- Event Handling (event folder): Implements a pub/sub mechanism so that the system responds to blockchain events related to leases and deployment manifests.
- Gateway (gateway folder): Provides a REST and gRPC server to expose administrative or operational APIs.
- Manifest Parsing (manifest folder): Processes and validates “manifest” files that describe deployment instructions and service configurations.
- Supporting Components: Other notable parts include operator logic (for hostname, inventory, IP management, etc.), client libraries (pkg/client, pkg/apis), and various integration tests configuration (integration folder) plus deployment templates (in the _docs and testdata folders).

##### Relationships and Interactions
- The Blockchain Event Listener feeds events into the Event subsystem.
- The Bid Engine uses these events and the dynamic on-chain configuration to compute the bids (and then likely communicates with the Command line interface’s entry points for transactions).
- Successful bid events trigger the Cluster Management system to deploy workloads according to corresponding deployment manifests (parsed by the Manifest component).
- The Cluster Management interacts with Kubernetes. Its modules (such as the kube builders, clients, and operator clients) control the underlying cluster resources.
- The Gateway serves as an external access point to the system (either for monitoring or administrative tasks) and communicates with the other internal components.
- The CLI (cmd) orchestrates these interactions during startup and operation.

##### Architectural Patterns & Design Principles
- Modular design: The project is clearly split into well-defined modules/subsystems (bidengine, cluster, gateway, etc.) which helps in maintainability and testability.
- Event-driven architecture: The usage of a pub/sub mechanism and the focus on reacting to blockchain event triggers stand out.
- Microservice/MVC-like separation: Although it’s a daemon process, responsibilities are decoupled between event handling, bidding logic, and cluster management.
- Extensibility: Multiple directories (e.g., different “operator” folders) suggest that the provider supports a variety of backends and can be easily extended beyond Kubernetes.

##### Inclusions
- Individual modules such as:
- Blockchain Event Listener (source of events)
- Event System (pub/sub mechanism)
- Bid Engine (pricing and bidding logic)
- Cluster Management (with in-depth Kubernetes interaction details, including deployment builders, kube clients, and operator components)
- Gateway (REST/gRPC server)
- CLI/Daemon Start-up (cobra based entry point)
- Manifest Parser (processing deployment manifest files)
- Optionally, illustrate supporting tools and configurations present in the file tree like Kubernetes manifests (_docs/kustomize, _run, etc.) to emphasize deployment and integration aspects.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Event Ingestion"
        BE["Blockchain Event Listener"]:::external
        ES["Event System"]:::internal
    end

    subgraph "Core Daemon Services"
        CLI["CLI/Daemon Bootstrapping (Cobra)"]:::internal
        BE2["Bid Engine"]:::internal
        MP["Manifest Parser"]:::internal
    end

    subgraph "Cluster & API"
        CM["Cluster Manager"]:::internal
        GW["Gateway (REST/gRPC)"]:::internal
    end

    subgraph "External Systems"
        K8s["Kubernetes Cluster"]:::external
    end

    %% Connections
    BE -->|"triggers"| ES
    CLI -->|"orchestrates"| ES
    CLI -->|"orchestrates"| BE2
    CLI -->|"orchestrates"| MP
    ES -->|"on-chain_events"| BE2
    ES -->|"on-chain_events"| CM
    BE2 -->|"initiates_tx"| CLI
    MP -->|"parse-manifests"| CM
    CM -->|"deploys"| K8s
    GW -->|"admin_control"| ES
    GW -->|"admin_control"| CM

    %% Click Events
    click BE2 "https://github.com/akash-network/provider/tree/main/bidengine/"
    click CM "https://github.com/akash-network/provider/tree/main/cluster/"
    click CLI "https://github.com/akash-network/provider/tree/main/cmd/"
    click ES "https://github.com/akash-network/provider/blob/main/event/events.go"
    click GW "https://github.com/akash-network/provider/tree/main/gateway/"
    click MP "https://github.com/akash-network/provider/blob/main/manifest/parse.go"

    %% Styles
    classDef external fill:#fde2e2,stroke:#a83232,stroke-width:2px;
    classDef internal fill:#e2f0fd,stroke:#3264a8,stroke-width:2px;
```
