# boomerang-io/flow.services architecture

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

- Interactive diagram: https://gitdiagram.com/boomerang-io/flow.services
- Repository: https://github.com/boomerang-io/flow.services

## Overview

##### Main Components
- Flow Service (located in service-flow): Exposes v2 RESTful APIs for front-end consumption including user/team management, relationship graphs, scheduling, authentication/authorization, and more.
- Engine Service (located in service-engine): Acts as the workflow orchestrator that executes workflows as Directed Acyclic Graphs (DAGs). This service “drives” the workflow execution and passes events to the handlers.
- Handler Service (located in service-handler): Listens for events from the Engine Service and executes tasks (the default implementation uses Tekton on Kubernetes, though additional handlers can be integrated).
- Common Library (lib-common): Contains shared domain models, entities, enums, and utility classes that are used across the services for consistency.
- External and Infrastructure Components:
- MongoDB: Used by the services for storage, including configuring TTL indexes (lock mechanism) and scheduling jobs (via Quartz).
- Kubernetes & Tekton: The Handler service uses Tekton for executing tasks on Kubernetes.
- CloudEvents: The services are designed to publish and consume CloudEvents.
- Quartz Scheduler: For distributed and scheduled job execution in the Flow service.

##### Relationships and Data Flow
- External Requests come in (HTTP calls) and are handled initially by the Flow Service.
- The Flow Service communicates with the Engine Service using HTTP, handing off requests for workflow execution.
- The shared lib-common ensures consistent entity and model definitions across all services.

##### Architectural Patterns & Design Principles
- Use a microservices or service-oriented architecture (even though they sit in a monorepo) by clearly separating Flow, Engine, and Handler responsibilities.
- The architecture is event-driven – highlight the asynchronous event dispatching from Engine to Handlers.
- Abstraction with the common library, which helps maintain consistency across services.
- Use of distributed locking (via the Mongo TTL based lock implementation) for handling concurrency.
- Usage of external scheduling (Quartz) and external container orchestration (Kubernetes/Tekton).

##### Technologies and Frameworks
- Java 21 and Spring Boot 3 for service development.
- Maven for build management.
- Docker (see Dockerfiles in each service) for containerization.
- MongoDB for data persistence.
- Quartz for scheduling.
- Tekton and Kubernetes for task execution.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Node Definitions %%
    Client["External Requests"]:::ext

    subgraph "Services"
        direction TB
        FlowS["Flow Service<br/>(v2 RESTful APIs)"]:::service
        EngineS["Engine Service<br/>(Workflow Orchestration)"]:::service
        HandlerS["Handler Service<br/>(Event Handlers)"]:::service
    end

    subgraph "Shared Library"
        Lib["Common Library<br/>(Shared Models & Utilities)"]:::library
    end

    subgraph "External Systems"
        direction TB
        MongoDB["MongoDB<br/>(Data Persistence)"]:::external
        Quartz["Quartz Scheduler<br/>(Job Scheduling)"]:::external
        KubeTekton["Kubernetes/Tekton<br/>(Task Execution)"]:::external
        CloudEvents["CloudEvents<br/>(Event Messaging)"]:::external
    end

    %% Service Communication %%
    Client -->|"HTTP"| FlowS
    FlowS -->|"HTTP"| EngineS
    EngineS -->|"Events"| HandlerS

    %% Shared Library Usage %%
    FlowS ---|"Uses"| Lib
    EngineS ---|"Uses"| Lib
    HandlerS ---|"Uses"| Lib

    %% External Integrations %%
    FlowS -->|"Schedules"| Quartz
    FlowS -->|"Lock/Jobs"| MongoDB
    EngineS -->|"Stores"| MongoDB
    EngineS -->|"Publishes"| CloudEvents
    HandlerS -->|"Executes"| KubeTekton
    HandlerS -->|"Consumes"| CloudEvents

    %% Click Events %%
    click FlowS "https://github.com/boomerang-io/flow.services/tree/main/service-flow/src/main/java/io/boomerang"
    click EngineS "https://github.com/boomerang-io/flow.services/tree/main/service-engine/src/main/java/io/boomerang/engine"
    click HandlerS "https://github.com/boomerang-io/flow.services/tree/main/service-handler/src/main/java/io/boomerang/controller"
    click Lib "https://github.com/boomerang-io/flow.services/tree/main/lib-common/src/main/java/io/boomerang/common"

    %% Classes / Styling %%
    classDef service fill:#cce5ff,stroke:#004085,stroke-width:2px;
    classDef library fill:#d4edda,stroke:#155724,stroke-width:2px;
    classDef external fill:#f8d7da,stroke:#721c24,stroke-width:2px;
    classDef ext fill:#fff3cd,stroke:#856404,stroke-width:2px;
```
