# phonepe/drove architecture

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

- Interactive diagram: https://gitdiagram.com/phonepe/drove
- Repository: https://github.com/phonepe/drove

## Overview

##### Main Components of the System
- Drove Controller: This is the “brain” of the orchestrator. It handles orchestration logic, state management, scheduling, state machine transitions (through the statemachine module), API endpoints (with its UI/resource modules), event logging, and error handling.
- Drove Executor: This module is responsible for actual container execution. It manages tasks via its own state machine, performs healthchecks, gathers resource metrics, and communicates with the controller.
- Authentication Module: The drove-authentication project provides security features like basic auth, JWT token management, and client filtering to secure inter-service communications.
- Client Components: Projects such as drove-client and drove-client-httpcomponent-transport encapsulate the logic for remote communications between components (for example, sending execution requests or receiving state updates).
- Common & Models: The drove-common and drove-models modules serve as the shared libraries for utility logic, communication protocols (messages, events, API responses), and domain models that are exchanged across different system components.
- Discovery/Leader Election: Several discovery modules (drove-hazelcast-discovery and drove-ignite-discovery) are used to support cluster membership, leader election, and state synchronization across cluster nodes.
- Event and Job Execution: The drove-events-client and drove-jobexecutor modules indicate that the system also performs asynchronous event handling and job management, likely integrating with container lifecycle events.
- State Machines: Finally, the drove-statemachine module encapsulates the orchestration process for state transitions in application instances and tasks.

##### Out the Relationships and Interactions
- Bidirectional communication lines between controller and executor, likely via HTTP-based messaging (using the drove-client libraries) and via dedicated communication components (e.g. RemoteExecutorMessageSender and RemoteControllerMessageSender).
- That both controller and executor use common libraries and models to exchange messages – these should be shown as a central shared component.
- Incorporate the authentication service as a middleware layer that sits in front of API endpoints and inter-service calls.
- Optionally, consider showing the packaging/deployment side (docker files, debian, rpm build directories) as an orthogonal concern that influences how the services are deployed in a production environment.

##### Architectural Patterns and Technologies
- Modular, microservices-like decomposition: Each subproject is a standalone Maven module, reinforcing the separation of concerns.
- State Machine Patterns: Both the controller and executor use state machine implementations to manage application and task lifecycles.
- Client/Server Communications: REST or HTTP-based communication channels exist between components, assisted by the client transport modules.
- Discovery and Leader Election: The use of Hazelcast and Ignite indicates distributed coordination strategies.
- Packaging & Deployment: The presence of Dockerfile, Podman profiles, debian packaging, and rpmbuild scripts indicate that containerization and OS-level packaging are integral to deployment.

##### Additional Details
- Document the flow of a container lifecycle – starting from an application submission (via an API in the controller), processing through state transitions, command forwarding to the executor, and event feedback from the executor back to the controller.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Orchestration Domain
    subgraph "Orchestration Domain"
        controller("Drove Controller<br>Orchestration & API Endpoints"):::orchestration
        statemachine("State Machines<br>State Transitions"):::orchestration
    end

    %% Execution Domain
    subgraph "Execution Domain"
        executor("Drove Executor<br>Task Execution & Resource Management"):::execution
        event1("Drove Events Client<br>Async Events"):::execution
        event2("Drove Job Executor<br>Job Management"):::execution
    end

    %% Core Services
    subgraph "Core Services"
        subgraph "Authentication"
            auth("Authentication Module<br>Basic Auth & JWT"):::core
        end
        subgraph "Client Components"
            client1("Drove Client"):::core
            client2("HTTP Component Transport"):::core
        end
        subgraph "Common & Models"
            common1("Drove Common"):::shared
            common2("Drove Models"):::shared
        end
        subgraph "Discovery Services"
            discovery1("Drove Hazelcast Discovery"):::core
            discovery2("Drove Ignite Discovery"):::core
        end
    end

    %% Connections between Core Services and Orchestration Domain
    client1 --> auth
    client2 --> auth
    auth --> controller
    client1 -- "bidirectional" --- controller
    client2 -- "bidirectional" --- controller

    %% Connections between Orchestration and Execution Domains
    controller -- "command" --- executor

    %% State Machine usage
    controller --> statemachine
    executor --> statemachine

    %% Shared Common Libraries usage
    controller --> common1
    controller --> common2
    executor --> common1
    executor --> common2

    %% Discovery Services interactions
    controller --> discovery1
    controller --> discovery2
    executor --> discovery1
    executor --> discovery2

    %% Event feedback from Executor to Controller
    executor --> event1
    executor --> event2
    event1 --> controller
    event2 --> controller

    %% Click Events
    click controller "https://github.com/phonepe/drove/tree/master/drove-controller/"
    click executor "https://github.com/phonepe/drove/tree/master/drove-executor/"
    click auth "https://github.com/phonepe/drove/tree/master/drove-authentication/"
    click client1 "https://github.com/phonepe/drove/tree/master/drove-client/"
    click client2 "https://github.com/phonepe/drove/tree/master/drove-client-httpcomponent-transport/"
    click common1 "https://github.com/phonepe/drove/tree/master/drove-common/"
    click common2 "https://github.com/phonepe/drove/tree/master/drove-models/"
    click discovery1 "https://github.com/phonepe/drove/tree/master/drove-hazelcast-discovery/"
    click discovery2 "https://github.com/phonepe/drove/tree/master/drove-ignite-discovery/"
    click event1 "https://github.com/phonepe/drove/tree/master/drove-events-client/"
    click event2 "https://github.com/phonepe/drove/tree/master/drove-jobexecutor/"
    click statemachine "https://github.com/phonepe/drove/tree/master/drove-statemachine/"

    %% Styles
    classDef orchestration fill:#FFCCBC,stroke:#E64A19,stroke-width:2px;
    classDef execution fill:#C5E1A5,stroke:#7CB342,stroke-width:2px;
    classDef core fill:#BBDEFB,stroke:#1976D2,stroke-width:2px;
    classDef shared fill:#FFF59D,stroke:#FBC02D,stroke-width:2px;
```
