# opsway-io/boomerang architecture

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

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

## Overview

##### Project type and purpose
- From the README and file names, Boomerang is an open-source Go library for distributed, recurring task scheduling built on top of Redis. It is not a full-stack web app or microservices suite, but rather a client library that you embed in your Go processes to share a common Redis-backed scheduler.

##### File structure
- Top-level Go modules (go.mod, go.sum) indicate a standalone library.
- schedule.go / task.go contain the core scheduler and task data-structures.
- schedule_test.go holds unit tests.
- docker-compose.yaml spins up a Redis instance for local testing.
- .github/workflows/test.yaml defines CI to run tests on every PR.

##### README for additional insights
- Shows how client code calls `sch.Add(…)` to schedule a recurring task, and `sch.On(…)` to register a callback.
- Implies the scheduler polls Redis for due tasks, executes the callback, then reschedules the next run.

##### Main components
a. Application process (your Go service)
b. Boomerang client library inside that process
c. Redis instance (single node or cluster)
d. Task execution callback (user code)
e. (Optional) Docker-Compose environment for local dev

##### Relationships and data flows
- At startup, your Go process loads the Boomerang library.
- When you call `sch.Add(ctx, task, interval, startTime)`, the library performs a Redis ZADD (or similar) to insert the task into a sorted set keyed by next execution timestamp.
- The scheduler goroutine inside the library continuously polls Redis (e.g., via ZRANGEBYSCORE) for tasks whose score ≤ now.
- On each tick, due tasks are popped (e.g., via a Lua script or transactional ZPOPMIN/COPY pattern), the callback registered by `sch.On(...)` is invoked, and then the task is rescheduled by another ZADD with an updated timestamp.
- All instances of your service share the same Redis backend, so they coordinate to avoid double-execution.

##### Architectural patterns and design principles
- Brokerless distributed scheduling via Redis sorted sets
- Poll-and-pop pattern for work coordination
- Idempotent task registration and rescheduling
- Horizontal scalability: multiple Go processes can run side-by-side

##### Relevant technologies
- Go modules (go.mod)
- Redis (sorted sets & optional Lua scripting)
- Docker-Compose for local Redis environment
- GitHub Actions for CI

##### Essential elements without over-splitting
- Runtime interaction between your app, the library, and Redis.

## Diagram (Mermaid)

```mermaid
flowchart TD
    GoApp["Go Application"]:::user
    subgraph "Boomerang Scheduler Library"
        Schedule["schedule.go"]:::library
        Task["task.go"]:::library
        Tests["schedule_test.go"]:::library
    end
    Redis["Redis Sorted Set"]:::external
    Callback["User Callback Handler"]:::user
    Docker["Docker-Compose (Local Redis)"]:::infra
    CI["CI Pipeline (GitHub Actions)"]:::infra
    GoMod["go.mod"]:::library
    GoSum["go.sum"]:::library
    Docs["README.md"]:::infra
    License["LICENSE.md"]:::infra
    GitIgnore[".gitignore"]:::infra

    GoApp -->|"sch.Add() (ZADD)"| Redis
    Redis <-->|"ZRANGEBYSCORE Poll"| Schedule
    Schedule -->|"invoke callback"| Callback
    Callback -->|"business logic"| GoApp
    Schedule -->|"reschedule ZADD"| Redis
    Docker -->|starts| Redis
    CI -->|runs tests| Tests

    click Schedule "https://github.com/opsway-io/boomerang/blob/master/schedule.go"
    click Task "https://github.com/opsway-io/boomerang/blob/master/task.go"
    click Tests "https://github.com/opsway-io/boomerang/blob/master/schedule_test.go"
    click Docker "https://github.com/opsway-io/boomerang/blob/master/docker-compose.yaml"
    click CI "https://github.com/opsway-io/boomerang/blob/master/.github/workflows/test.yaml"
    click GoMod "https://github.com/opsway-io/boomerang/blob/master/go.mod"
    click GoSum "https://github.com/opsway-io/boomerang/blob/master/go.sum"
    click Docs "https://github.com/opsway-io/boomerang/blob/master/README.md"
    click License "https://github.com/opsway-io/boomerang/blob/master/LICENSE.md"
    click GitIgnore "https://github.com/opsway-io/boomerang/blob/master/.gitignore"

    classDef library fill:#D6EAF8,stroke:#21618C,color:#1B4F72
    classDef external fill:#F5B7B1,stroke:#C0392B,color:#641E16
    classDef user fill:#D5F5E3,stroke:#27AE60,color:#145A32
    classDef infra fill:#FCF3CF,stroke:#B7950B,color:#7D6608
```
