# miet-lambda/balancer architecture

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

- Interactive diagram: https://gitdiagram.com/miet-lambda/balancer
- Repository: https://github.com/miet-lambda/balancer

## Overview

##### Project Type and Purpose
- The project is a Kotlin-based backend service built with Gradle.
- Its purpose, as described in the README, is to balance the load among available instances of an external “lambda executor” service. It does so by querying a Postgres database for a list of available instances (the instances are stored in an “instances” table) and verifying user account balances before routing a request.

##### Analysis of the File Structure
- Top-Level Files:
- Gradle wrapper scripts and build files indicate that the project uses Gradle as its build system.
- The README and .gitignore files describe the project, while gradlew and gradlew.bat indicate cross-platform support.
- Source Directory (src/main/kotlin):
- Application.kt likely serves as the entry point to the service.
- Routing.kt sets up the endpoints and request handling.
- LambdaExecutor.kt and LambdaExecutorProvider.kt are central to managing or interfacing with the external lambda executor instances.
- NegotiationModels.kt probably contains data definitions or business logic models.
- Database Integration:
- The db package contains DataProvider.kt and PostgresDatabase.kt, indicating an abstraction layer for connecting to and interacting with a Postgres database.
- Resources:
- The presence of a logback.xml file shows that the project uses Logback for logging.

a. Main Components:
- Client/API Gateway (or external client): The external point of entry making requests for lambda execution services.
- Balancer Service (this service):
- Entry Point (Application.kt): Initiates the service and manages configuration.
- Routing (Routing.kt): Handles incoming requests and directs them appropriately.
- Business Logic:
- Lambda Executor Components (LambdaExecutor.kt, LambdaExecutorProvider.kt) that encapsulate logic to choose between lambda executor instances.
- Models (NegotiationModels.kt) that support the negotiation and selection process.
- Database Layer:
- DataProvider.kt and PostgresDatabase.kt to query and update the ‘instances’ table and possibly other supporting tables (e.g., user balance records).
- External Lambda Executors:
- These are separate services (as noted by the external link in the README) which the balancer interacts with.

b. Relationships and Interactions:
- Incoming requests hit the Balancer Service’s routing layer.
- The service consults the database to retrieve available executor instances.
- It checks if a given executor is “available” and verifies user account balances.
- Once validated, the service routes the request to an appropriate lambda executor instance.
- There is a feedback loop where the service might update instance or user balance data in the database after execution.

c. Architectural Patterns and Design Principles:
- Separation of concerns: Clearly split between handling routing, executing business logic (load balancing), and database interaction.
- Dependency abstraction: Use of provider classes and data access objects (DAO) to interact with both Lambda Executors and the database.
- Modularity: Each component (routing, executor logic, and database access) exists in its own module or package, making the system more maintainable.

d. Technologies, Frameworks, and Libraries:
- Kotlin as the primary programming language.
- Gradle as the build tool.
- Postgres (as implied by the PostgresDatabase.kt) for data persistence.
- Logback (configured via logback.xml) for logging.
- Integration with external lambda executor services (from the README’s link).

## Diagram (Mermaid)

```mermaid
graph TD
    %% External Systems
    Client("Client/API Gateway"):::external
    External("External Lambda Executors"):::external

    %% Balancer Service
    subgraph "Balancer Service"
        App("Balancer Service Entry Point (Application.kt)"):::service
        Routing("Routing & Request Handling (Routing.kt)"):::service
        App -->|"initiate"| Routing
    end

    %% Configuration
    subgraph "Configuration"
        Logging("Logging Configuration (logback.xml)"):::config
    end

    %% Load Balancer Core
    subgraph "Load Balancer Core"
        LambdaExec("Lambda Executor (LambdaExecutor.kt)"):::logic
        LambdaProv("Lambda Executor Provider (LambdaExecutorProvider.kt)"):::logic
        Models("Business Models (NegotiationModels.kt)"):::logic
    end

    %% Database Layer
    subgraph "Database Layer"
        DP("Data Provider (DataProvider.kt)"):::database
        PG("Postgres Database (PostgresDatabase.kt)"):::database
    end

    %% Connections between components
    Client -->|"request"| App
    App -->|"setup_log"| Logging
    Routing -->|"invoke"| LambdaExec
    Routing -->|"invoke"| LambdaProv
    Routing -->|"invoke"| Models
    LambdaExec -->|"query"| DP
    LambdaProv -->|"query"| DP
    DP -->|"response"| LambdaExec
    LambdaExec -->|"connect"| PG
    PG -->|"support"| LambdaExec
    LambdaExec -->|"route"| External
    External -->|"response"| LambdaExec
    LambdaExec -->|"send"| Routing
    Routing -->|"return"| App
    App -->|"deliver"| Client

    %% Click Events
    click App "https://github.com/miet-lambda/balancer/blob/master/src/main/kotlin/Application.kt"
    click Routing "https://github.com/miet-lambda/balancer/blob/master/src/main/kotlin/Routing.kt"
    click LambdaExec "https://github.com/miet-lambda/balancer/blob/master/src/main/kotlin/LambdaExecutor.kt"
    click LambdaProv "https://github.com/miet-lambda/balancer/blob/master/src/main/kotlin/LambdaExecutorProvider.kt"
    click Models "https://github.com/miet-lambda/balancer/blob/master/src/main/kotlin/NegotiationModels.kt"
    click DP "https://github.com/miet-lambda/balancer/blob/master/src/main/kotlin/db/DataProvider.kt"
    click PG "https://github.com/miet-lambda/balancer/blob/master/src/main/kotlin/db/PostgresDatabase.kt"
    click Logging "https://github.com/miet-lambda/balancer/blob/master/src/main/resources/logback.xml"

    %% Styles
    classDef external fill:#f9c,stroke:#333,stroke-width:2px;
    classDef service fill:#bbf,stroke:#333,stroke-width:2px;
    classDef logic fill:#bfb,stroke:#333,stroke-width:2px;
    classDef database fill:#ffb,stroke:#333,stroke-width:2px;
    classDef config fill:#fcf,stroke:#333,stroke-width:2px;
```
