Architecture Overview

System Diagram

                    +------------------------------------------+
                    |           Exekra Hub          |
                    |              (Windows Service)            |
                    |                                          |
                    |  +----------------+  +----------------+  |
                    |  |   Frontend     |  |    Backend     |  |
                    |  |   (HTTPS)      |  |   (internal)   |  |
                    |  +-------+--------+  +-------+--------+  |
                    |          |    API proxy /api/  |          |
                    |          +--------------------+          |
                    +------------|----------------------------|+
                                 |                            |
                    +------------v---+              +---------v------+
                    |  PostgreSQL    |              |     Redis      |
                    |  (Database)    |              |   (Queue)      |
                    +----------------+              +----------------+

     +-------------------+-------------------+-------------------+
     |                   |                   |                   |
+----v-----+       +----v-----+       +----v-----+       +----v-----+
|  Runner  |       |  Runner  |       |  Runner  |       |  Runner  |
|    #1    |       |    #2    |       |    #3    |       |    #4    |
+----------+       +----------+       +----------+       +----------+

Component Responsibilities

Hub

The hub is the central management server. It provides the web interface (dashboard, workflow management, runner monitoring), REST API, workflow storage, execution scheduling via cron and webhooks, runner management (registration, authentication, health monitoring, work assignment), license enforcement, and audit logging.

Runner

The runner is an Electron-based desktop agent that executes workflows on Windows machines. It authenticates with the Hub, sends heartbeats every 30 seconds, polls for assigned work every 5 seconds, and reports execution results including logs and performance metrics.

Database (PostgreSQL)

Stores all persistent state: users, workflows, versions, executions, runners, triggers, license data (encrypted), and audit logs.

Redis

Provides the execution queue via BullMQ. Decouples execution creation from runner assignment with 5 concurrent workers, exponential backoff retry (3 attempts), and automatic fallback to direct assignment if Redis is unavailable.

Execution Modes

Execution Flow Summary

1. A user, schedule, or webhook creates an execution request
2. The Hub validates the license and retrieves the published workflow version
3. The execution is placed in the BullMQ queue with status QUEUED
4. A queue worker finds an available runner and assigns the execution
5. The runner picks up the assignment on its next poll cycle (every 5 seconds)
6. The runner executes the workflow graph node-by-node, buffering logs
7. On completion, the runner sends the final status, logs, and metrics to the Hub