# nikunja11/task-scheduler architecture

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

- Interactive diagram: https://gitdiagram.com/nikunja11/task-scheduler
- Repository: https://github.com/nikunja11/task-scheduler

## Overview

##### Project type and purpose
- This is a Java-based task scheduling library (packaged via Maven). There is no UI or network layer; instead it provides a core scheduling engine you embed in your application to define, store, and execute units of work (Tasks) via an event-driven, state-machine approach.

##### File structure
- pom.xml: Maven build, dependency management.
- src/main/java/com/scheduler/core: interfaces and abstractions (Task, InputProvider, TaskExecutor, TaskExecutionContext).
- com/scheduler/event: event definitions, a publisher and a bus to broadcast WorkflowEvents.
- com/scheduler/listener: event listener interfaces and example implementation (LoggingEventListener).
- com/scheduler/repo: repository interfaces and an in-memory implementation for storing task metadata.
- com/scheduler/scheduler: the TaskScheduler component that orchestrates task lifecycles.
- com/scheduler/state: a state-pattern implementation for TaskState (Init, Ready, Running, Success, Failed).
- com/scheduler/examples: sample code exercising the library (DataProcessingExample).

##### README
- Minimal: the project name. We infer from code structure that the focus is on an embeddable, event-driven scheduler.

a. Main components
- TaskScheduler – the orchestrator that polls the repository, transitions states, and triggers execution.
- TaskRepository – persistent store for task definitions and statuses (e.g. InMemoryTaskRepository).
- TaskState Machine – encapsulates valid state transitions (Init → Ready → Running → Success/Failed).
- TaskExecutor – invokes the actual work defined by a Task implementation via TaskExecutionContext and InputProvider.
- WorkflowEventBus & TaskEventPublisher – event-driven communication channel for broadcasting state changes.
- WorkflowEventListener(s) – e.g. LoggingEventListener, user-provided hooks for reacting to events.
- Example client code – DataProcessingExample, illustrating how an application uses the above components.

b. Relationships and interactions
1. Client code instantiates and configures TaskScheduler, injecting a TaskRepository, TaskExecutor, InputProvider, and optionally listeners.
2. TaskScheduler polls or is triggered to pick up pending tasks from TaskRepository.
3. For each fetched Task, TaskScheduler drives the state machine: calls state.enter/exit methods, updates the TaskState in the repository.
4. Before and after each state transition, TaskEventPublisher posts WorkflowEvents onto WorkflowEventBus.
5. Registered WorkflowEventListeners receive events and perform side-effects (e.g., logging, metrics, retries).
6. When a task reaches the Running state, TaskScheduler invokes TaskExecutor.execute(context) which runs the actual Task logic.
7. Upon completion or exception, TaskExecutor signals success or failure, triggering a state transition to SuccessTaskState or FailedState.
8. Final state is persisted, relevant events are published, and scheduling continues or terminates.

c. Architectural patterns and principles
- State Pattern: TaskState classes encapsulate behavior per state.
- Event-Driven: decoupled communication via WorkflowEventBus and listeners.
- Dependency Injection (via constructors) to swap repository or executor implementations.
- Modular layering: core abstractions vs. pluggable implementations vs. application examples.

d. Key technologies and frameworks
- Java 8+
- Maven (pom.xml)
- No external frameworks by default; all components are custom (could be extended to use Spring DI, a database-backed TaskRepository, etc.).

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Client example
    subgraph "Client Example"
        DPE["DataProcessingExample"]:::example
    end

    %% Core engine components
    subgraph "Core Engine"
        TS["TaskScheduler"]:::core
    end

    %% Repository layer
    subgraph "Repository Layer"
        TR["TaskRepository (interface)"]:::pluggable
        IMTR["InMemoryTaskRepository"]:::pluggable
    end

    %% State machine
    subgraph "State Machine"
        TSIF["TaskState (interface)"]:::core
        ATS["AbstractTaskState"]:::core
        ITS["InitTaskState"]:::core
        RTS["ReadyTaskState"]:::core
        RNS["RunningTaskState"]:::core
        SSS["SuccessTaskState"]:::core
        FS["FailedState"]:::core
    end

    %% Event system
    subgraph "Event System"
        WEB["WorkflowEventBus"]:::event
        TEP["TaskEventPublisher"]:::event
        WE["WorkflowEvent"]:::event
        WET["WorkflowEventType"]:::event
    end

    %% Listeners
    subgraph "Listeners"
        WFL["WorkflowEventListener"]:::pluggable
        LEL["LoggingEventListener"]:::pluggable
    end

    %% Core abstractions
    subgraph "Core Abstractions"
        TSK["Task"]:::pluggable
        IP["InputProvider"]:::pluggable
        TEC["TaskExecutionContext"]:::pluggable
        TEX["TaskExecutor"]:::pluggable
    end

    %% Connections
    DPE -->|"instantiates & configures"| TS
    TS -->|"fetchPendingTasks()"| TR
    TS -->|"CRUD on tasks"| IMTR
    TS -->|"transitionState()"| TSIF
    TSIF --> ATS
    ATS --> ITS
    ATS --> RTS
    ATS --> RNS
    ATS --> SSS
    ATS --> FS
    TSIF -->|"update state"| TR
    TSIF -->|"update state"| IMTR
    TSIF -->|"publishEvent()"| TEP
    TEP -->|"post()"| WEB
    WEB -->|"subscribe()"| WFL
    WFL -->|"implemented by"| LEL
    TS -->|"executeTask()"| TEX
    TEX -->|"uses"| TSK
    TEX -->|"uses"| IP
    TEX -->|"uses"| TEC

    %% Click events
    click TS "https://github.com/nikunja11/task-scheduler/blob/main/src/main/java/com/scheduler/scheduler/TaskScheduler.java"
    click TR "https://github.com/nikunja11/task-scheduler/blob/main/src/main/java/com/scheduler/repo/TaskRepository.java"
    click IMTR "https://github.com/nikunja11/task-scheduler/blob/main/src/main/java/com/scheduler/repo/InMemoryTaskRepository.java"
    click TSIF "https://github.com/nikunja11/task-scheduler/blob/main/src/main/java/com/scheduler/state/TaskState.java"
    click ATS "https://github.com/nikunja11/task-scheduler/blob/main/src/main/java/com/scheduler/state/AbstractTaskState.java"
    click ITS "https://github.com/nikunja11/task-scheduler/blob/main/src/main/java/com/scheduler/state/InitTaskState.java"
    click RTS "https://github.com/nikunja11/task-scheduler/blob/main/src/main/java/com/scheduler/state/ReadyTaskState.java"
    click RNS "https://github.com/nikunja11/task-scheduler/blob/main/src/main/java/com/scheduler/state/RunningTaskState.java"
    click SSS "https://github.com/nikunja11/task-scheduler/blob/main/src/main/java/com/scheduler/state/SuccessTaskState.java"
    click FS "https://github.com/nikunja11/task-scheduler/blob/main/src/main/java/com/scheduler/state/FailedState.java"
    click TSK "https://github.com/nikunja11/task-scheduler/blob/main/src/main/java/com/scheduler/core/Task.java"
    click IP "https://github.com/nikunja11/task-scheduler/blob/main/src/main/java/com/scheduler/core/InputProvider.java"
    click TEC "https://github.com/nikunja11/task-scheduler/blob/main/src/main/java/com/scheduler/core/TaskExecutionContext.java"
    click TEX "https://github.com/nikunja11/task-scheduler/blob/main/src/main/java/com/scheduler/core/TaskExecutor.java"
    click WEB "https://github.com/nikunja11/task-scheduler/blob/main/src/main/java/com/scheduler/event/WorkflowEventBus.java"
    click TEP "https://github.com/nikunja11/task-scheduler/blob/main/src/main/java/com/scheduler/event/TaskEventPublisher.java"
    click WE "https://github.com/nikunja11/task-scheduler/blob/main/src/main/java/com/scheduler/event/WorkflowEvent.java"
    click WET "https://github.com/nikunja11/task-scheduler/blob/main/src/main/java/com/scheduler/event/WorkflowEventType.java"
    click WFL "https://github.com/nikunja11/task-scheduler/blob/main/src/main/java/com/scheduler/listener/WorkflowEventListener.java"
    click LEL "https://github.com/nikunja11/task-scheduler/blob/main/src/main/java/com/scheduler/listener/LoggingEventListener.java"
    click DPE "https://github.com/nikunja11/task-scheduler/blob/main/src/main/java/com/scheduler/examples/DataProcessingExample.java"
    click pom "https://github.com/nikunja11/task-scheduler/blob/main/pom.xml"

    %% Styles
    classDef core fill:#bbdefb,stroke:#1976d2,stroke-width:1px
    classDef pluggable fill:#c8e6c9,stroke:#388e3c,stroke-width:1px
    classDef example fill:#ffe0b2,stroke:#f57c00,stroke-width:1px
    classDef event fill:#d1c4e9,stroke:#7e57c2,stroke-width:1px
```
