# brahma-fi/brahma-builder architecture

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

- Interactive diagram: https://gitdiagram.com/brahma-fi/brahma-builder
- Repository: https://github.com/brahma-fi/brahma-builder

## Overview

##### Project Type and Purpose
- This project is a high-performance, scalable workflow scheduling engine built on top of Temporal. Its goal is to orchestrate custom strategies (like the Morpho Yield Optimizer) with fault tolerance, automatic retries, and integration with the Brahma Builder Kit API.
- The README reinforces that this engine handles zero-config workflow scheduling and native integration with the Brahma ecosystem, indicating both a backend orchestration service and a degree of extensibility via multiple worker types (e.g., base-worker, morpho-worker).

##### Analyzing the File Structure
- Top-Level components:
- “app”: Contains subdirectories for cli, scheduler, and workers. This indicates that the application has a CLI component for managing workflows, a scheduling service, and worker processes that execute specific tasks.
- “cmd”: Contains the main entry point (main.go) which likely bootstraps the application and selects which mode to run (scheduler versus one of the workers).
- “internal”: Contains domain-specific entities, repositories, use cases (integrations, services, workflows), and orchestration logic. This gives insight into the core business logic.
- “pkg”: Holds shared utility libraries, including key management, logging, RPC, Temporal integration, and Vault integration.
- “deployment”: Includes Dockerfile(s) (e.g., for the Brahma Builder container) showing how the application is containerized and potentially deployed.
- “_scripts”: Contains scripts for executor and Vault setup which are essential for local development and integration with external services.
- “config” and “docs”: Provide configurations and architectural documentation (the latter can be referenced to see further design details).

##### Identifying Main Components
- Frontend (CLI): Represented by the CLI subdirectory under app/cli. It serves as an interface for triggering and managing workflows.
- Scheduler: Under app/scheduler, this serves as the central orchestrator which schedules and triggers activities using Temporal.
- Worker Processes: Under app/worker, there are distinct implementations (e.g., base worker and the morpho worker) that execute specific workflow activities.
- Temporal Engine: An underlying, external workflow orchestration engine that this service is built on. It coordinates job execution and state management across scheduler and workers.
- Configuration and Integration Services: The “internal” and “pkg” directories offer services for logging, RPC communications, key vault management, and integration with the Brahma Builder Kit API.
- Vault & Executor Scripts: Located under _scripts and pkg/vault, these components handle secure secret management (Vault) and dynamic execution or plugin setups (executor).
- Database/Storage: Though not explicitly named, repositories under “internal/repo” suggest data persistence for schedules, workflows, etc.

##### Relationships and Interactions
- The CLI component issues commands that are processed by the scheduler.
- The Scheduler (in app/scheduler) interacts with Temporal to schedule and manage workflows.
- Worker processes (both base and morpho) receive tasks from Temporal and execute the defined workflow activities.
- Integration components (in internal/usecase/integrations and services) abstract interactions with external systems such as the Brahma Builder Kit API.
- The Vault and Executor components, along with related scripts (_scripts/vault, _scripts/executor), facilitate dynamic configuration and secure handling of credentials and plugins.
- Internal packages (internal/entity, internal/usecase/workflows) define domain models and orchestrate the business logic between the scheduling engine and worker executions.
- Shared libraries (pkg/*) provide cross-cutting functionalities like logging, RPC communication, utility functions, and Temporal adapter.

##### Architectural Patterns and Design Principles
- Layered Architecture: Separation between command (cli), orchestration (scheduler), execution (workers), and supporting services (internal, pkg).
- Microservice/Component Separation: Although it’s a single repository, multiple components (scheduler, workers, CLI) are clearly separated, promoting separation of concerns.
- Plug-in Design: Presence of executor plugins and Vault configurations enable extensible integration with third-party services.
- Fault Tolerance and Retry Mechanisms: Intrinsic to the workflow scheduling engine built on Temporal, which handles retries and failure recovery.

- Supporting services (integrations, repository, and domain services) interacting with both the Scheduler and Workers.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Interface Layer
    subgraph "Interface Layer"
        CLI["CLI Interface"]:::interface
    end

    %% Core Services
    subgraph "Core Services"
        Scheduler["Scheduler Service"]:::core
        Temporal["Temporal Workflow Engine"]:::external
        Integration["Integration Services"]:::integration
        Repo["Repository/Persistence Layer"]:::repo
    end

    %% Worker Processes
    subgraph "Worker Processes"
        BaseWorker["Base Worker Process"]:::worker
        MorphoWorker["Morpho Worker Process"]:::worker
        Executor["Executor Plugin/Script Support"]:::executor
    end

    %% External & Utilities
    subgraph "External & Utilities"
        Vault["Vault Integration & Secret Management"]:::vault
        VaultSetup["Vault Setup Scripts"]:::vault
        Utils["Shared Libraries & Utilities"]:::utils
    end

    %% Connections
    CLI -->|"trigger"| Scheduler
    Scheduler -->|"schedules"| Temporal
    Temporal -->|"assigns task"| BaseWorker
    Temporal -->|"assigns task"| MorphoWorker
    Scheduler -->|"persists"| Repo
    Scheduler -->|"invokes"| Integration
    Integration -->|"uses"| Vault
    Integration -->|"executes"| Executor
    Vault -->|"configures"| VaultSetup

    %% Dashed links for utilities usage
    Scheduler -.->|"uses"| Utils
    Integration -.->|"uses"| Utils
    BaseWorker -.->|"uses"| Utils
    MorphoWorker -.->|"uses"| Utils

    %% Click Events
    click CLI "https://github.com/brahma-fi/brahma-builder/blob/main/app/cli/cli.go"
    click Scheduler "https://github.com/brahma-fi/brahma-builder/blob/main/app/scheduler/server.go"
    click BaseWorker "https://github.com/brahma-fi/brahma-builder/blob/main/app/worker/base/worker.go"
    click MorphoWorker "https://github.com/brahma-fi/brahma-builder/blob/main/app/worker/morpho/worker.go"
    click Temporal "https://github.com/brahma-fi/brahma-builder/blob/main/pkg/temporal/temporal.go"
    click Integration "https://github.com/brahma-fi/brahma-builder/tree/main/internal/usecase/integrations"
    click Repo "https://github.com/brahma-fi/brahma-builder/blob/main/internal/repo/schedule_repo.go"
    click Vault "https://github.com/brahma-fi/brahma-builder/blob/main/pkg/vault/vault.go"
    click VaultSetup "https://github.com/brahma-fi/brahma-builder/blob/main/_scripts/vault/setup_vault.sh"
    click Executor "https://github.com/brahma-fi/brahma-builder/blob/main/pkg/utils/executor/executor.go"
    click Utils "https://github.com/brahma-fi/brahma-builder/blob/main/pkg/log/logger.go"

    %% Class Definitions for coloring
    classDef interface fill:#f9c74f,stroke:#333,stroke-width:2px;
    classDef core fill:#90be6d,stroke:#333,stroke-width:2px;
    classDef worker fill:#577590,stroke:#333,stroke-width:2px,color:#fff;
    classDef external fill:#f94144,stroke:#333,stroke-width:2px;
    classDef integration fill:#f3722c,stroke:#333,stroke-width:2px;
    classDef repo fill:#43aa8b,stroke:#333,stroke-width:2px;
    classDef vault fill:#277da1,stroke:#333,stroke-width:2px,color:#fff;
    classDef executor fill:#f9844a,stroke:#333,stroke-width:2px;
    classDef utils fill:#6a4c93,stroke:#333,stroke-width:2px,color:#fff;
```
