# cap-js-community/event-queue architecture

> Architecture diagram of the GitHub repository cap-js-community/event-queue, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-04-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/cap-js-community/event-queue
- Repository: https://github.com/cap-js-community/event-queue

## Overview

1. This repository is a CAP Node.js plugin/framework for asynchronous event processing. The entry point is `cds-plugin.js`, which makes the package auto-attach to CAP applications. The public API lives in `src/index.js` and is backed by the core runtime modules under `src/`.

2. The central architectural boundary is the persisted event queue in the database. The CDS model in `db/Event.cds`, `db/Lock.cds`, and `db/index.cds` defines the queue and coordination tables that CAP apps deploy into their schema. The queue is the system of record for events until they are processed or cleaned up.

3. Event publication flows through `src/publishEvent.js` and `src/dbHandler.js`. Application code or CAP handlers enqueue work into the DB, where it becomes durable and visible to workers. Configuration is resolved through `src/config.js`, `src/constants.js`, and helper utilities in `src/shared/`.

4. Event consumption is handled by `src/processEventQueue.js`, with the processor abstraction in `src/EventQueueProcessorBase.js`. These modules implement the event execution lifecycle, including status handling, retry/error wrapping via `src/EventQueueError.js`, and transaction-aware processing.

5. Horizontal scaling and concurrency control are a major design point. `src/shared/distributedLock.js`, `src/runner/runner.js`, `src/runner/openEvents.js`, and `src/runner/runnerHelper.js` coordinate multiple application instances so only the right instance processes a given slice of the queue. `src/shared/WorkerQueue.js` and `src/shared/SetIntervalDriftSafe.js` support controlled execution and periodic scheduling.

6. Redis is used as an accelerator and coordination channel. The modules in `src/redis/` and `src/shared/redis/` implement pub/sub and client management so instances can react quickly to newly published events instead of relying only on polling. This is a low-latency path layered on top of the durable DB queue.

7. Periodic work is a first-class feature rather than an external cron dependency. `src/periodicEvents.js` and `src/shared/eventScheduler.js` drive scheduled execution, while the test suite includes dedicated periodic-event scenarios. The scheduler is integrated into the same queue/worker model as ordinary events.

8. There is explicit support for CAP outbox integration. `src/outbox/eventQueueAsOutbox.js` and `src/outbox/EventQueueGenericOutboxHandler.js` adapt the event queue to CAP’s outbox semantics, letting existing CAP services publish through the queue without changing their business code. This is a distinct integration boundary from the core queue engine.

9. Housekeeping and operational concerns are separated from the hot path. `src/housekeeping/EventQueueDeleteEvents.js` removes old queue entries, and `src/shared/eventQueueStats.js` plus `src/shared/PerformanceTracer.js` capture runtime health and performance data. `src/shared/openTelemetry.js` indicates optional observability hooks.

10. CAP service integration is demonstrated in `srv/` and `example-cap-server/`. The admin service in `srv/service/admin-service.js` exposes management functionality, while the example server shows a real consumer/producer setup with service facades, handlers, and CDS service definitions. This example is part of the repo’s architecture documentation by code.

11. The project is heavily test-driven across unit, integration, and end-to-end layers. `test/` covers core helpers and queue behavior, while `test-integration/` exercises Redis, HANA deployment, runner behavior, transaction handling, and periodic events. The `test/asset/outboxProject` fixture is especially useful for understanding how the plugin behaves inside a real CAP app.

12. In diagram terms, the main flow is: CAP app or outbox producer publishes an event into the DB queue; scheduler/runner instances discover open events; distributed locking and Redis coordination prevent duplicate work; a worker executes the handler inside CAP-managed transaction boundaries; housekeeping later removes completed records. The main external dependencies that shape the architecture are CAP Node.js, a relational database, and optionally Redis for cross-instance coordination.

Main entry points: [`src/processEventQueue.js`](https://github.com/cap-js-community/event-queue/blob/main/src/processEventQueue.js) (Process queue), [`src/dbHandler.js`](https://github.com/cap-js-community/event-queue/blob/main/src/dbHandler.js) (DB handler), [`src/outbox/eventQueueAsOutbox.js`](https://github.com/cap-js-community/event-queue/blob/main/src/outbox/eventQueueAsOutbox.js) (Outbox adapter), [`src/publishEvent.js`](https://github.com/cap-js-community/event-queue/blob/main/src/publishEvent.js) (Publish)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_g1["Package entry"]
  node_n1["cds-plugin<br/>plugin entry<br/>[cds-plugin.js]"]
  node_n2["Public API<br/>API surface<br/>[index.js]"]
end

subgraph group_g2["Core runtime"]
  node_n3["Init<br/>bootstrap<br/>[initialize.js]"]
  node_n4["Config<br/>settings<br/>[config.js]"]
  node_n5["Publish<br/>enqueue<br/>[publishEvent.js]"]
  node_n6[("DB handler<br/>persistence adapter<br/>[dbHandler.js]")]
  node_n7["Process queue<br/>consumer loop"]
  node_n8["Processor base<br/>execution base"]
  node_n9["Periodic events<br/>scheduler<br/>[periodicEvents.js]"]
end

subgraph group_g3["Persistence"]
  node_n10["Event schema<br/>cds model<br/>[Event.cds]"]
  node_n11["Lock schema<br/>cds model<br/>[Lock.cds]"]
  node_n12["DB index<br/>cds model<br/>[index.cds]"]
end

subgraph group_g4["Coordination"]
  node_n13["Runner<br/>worker coordinator<br/>[runner.js]"]
  node_n14["Open events<br/>dispatcher<br/>[openEvents.js]"]
  node_n15["Distributed lock<br/>coordination<br/>[distributedLock.js]"]
  node_n16["Redis pub<br/>pubsub<br/>[redisPub.js]"]
  node_n17["Redis sub<br/>pubsub<br/>[redisSub.js]"]
  node_n18["Redis client<br/>client layer<br/>[index.js]"]
end

subgraph group_g5["Integrations"]
  node_n19["Outbox adapter<br/>cap outbox"]
  node_n20["Outbox handler"]
  node_n22["Admin service<br/>cap service<br/>[admin-service.js]"]
  node_n23["Example app<br/>demo cap app<br/>[process-service.js]"]
end

subgraph group_g6["Ops"]
  node_n21["Housekeeping<br/>cleanup"]
end

node_n1 -->|"loads"| node_n2
node_n2 -->|"initializes"| node_n3
node_n3 -->|"reads"| node_n4
node_n5 -->|"persists"| node_n6
node_n6 -->|"stores"| node_n10
node_n6 -->|"coordinates"| node_n11
node_n12 -->|"includes"| node_n10
node_n12 -->|"includes"| node_n11
node_n7 -->|"executes via"| node_n8
node_n7 -->|"discovers"| node_n14
node_n14 -->|"claims"| node_n15
node_n13 -->|"orchestrates"| node_n14
node_n13 -->|"publishes"| node_n16
node_n17 -->|"uses"| node_n18
node_n16 -->|"uses"| node_n18
node_n9 -->|"enqueues"| node_n7
node_n19 -->|"implements"| node_n20
node_n19 -->|"publishes through"| node_n5
node_n21 -->|"cleans"| node_n10
node_n22 -->|"manages"| node_n7
node_n23 -->|"demonstrates"| node_n19
node_n23 -->|"produces"| node_n5

click node_n1 "https://github.com/cap-js-community/event-queue/blob/main/cds-plugin.js"
click node_n2 "https://github.com/cap-js-community/event-queue/blob/main/src/index.js"
click node_n3 "https://github.com/cap-js-community/event-queue/blob/main/src/initialize.js"
click node_n4 "https://github.com/cap-js-community/event-queue/blob/main/src/config.js"
click node_n5 "https://github.com/cap-js-community/event-queue/blob/main/src/publishEvent.js"
click node_n6 "https://github.com/cap-js-community/event-queue/blob/main/src/dbHandler.js"
click node_n7 "https://github.com/cap-js-community/event-queue/blob/main/src/processEventQueue.js"
click node_n8 "https://github.com/cap-js-community/event-queue/blob/main/src/EventQueueProcessorBase.js"
click node_n9 "https://github.com/cap-js-community/event-queue/blob/main/src/periodicEvents.js"
click node_n10 "https://github.com/cap-js-community/event-queue/blob/main/db/Event.cds"
click node_n11 "https://github.com/cap-js-community/event-queue/blob/main/db/Lock.cds"
click node_n12 "https://github.com/cap-js-community/event-queue/blob/main/db/index.cds"
click node_n13 "https://github.com/cap-js-community/event-queue/blob/main/src/runner/runner.js"
click node_n14 "https://github.com/cap-js-community/event-queue/blob/main/src/runner/openEvents.js"
click node_n15 "https://github.com/cap-js-community/event-queue/blob/main/src/shared/distributedLock.js"
click node_n16 "https://github.com/cap-js-community/event-queue/blob/main/src/redis/redisPub.js"
click node_n17 "https://github.com/cap-js-community/event-queue/blob/main/src/redis/redisSub.js"
click node_n18 "https://github.com/cap-js-community/event-queue/blob/main/src/shared/redis/index.js"
click node_n19 "https://github.com/cap-js-community/event-queue/blob/main/src/outbox/eventQueueAsOutbox.js"
click node_n20 "https://github.com/cap-js-community/event-queue/blob/main/src/outbox/EventQueueGenericOutboxHandler.js"
click node_n21 "https://github.com/cap-js-community/event-queue/blob/main/src/housekeeping/EventQueueDeleteEvents.js"
click node_n22 "https://github.com/cap-js-community/event-queue/blob/main/srv/service/admin-service.js"
click node_n23 "https://github.com/cap-js-community/event-queue/blob/main/example-cap-server/srv/handler/process-service.js"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_n1,node_n2 toneBlue
class node_n3,node_n4,node_n5,node_n6,node_n7,node_n8,node_n9 toneAmber
class node_n10,node_n11,node_n12 toneMint
class node_n13,node_n14,node_n15,node_n16,node_n17,node_n18 toneRose
class node_n19,node_n20,node_n22,node_n23 toneIndigo
class node_n21 toneTeal
```

## Components

### Package entry

Auto-attachment and public API entry points

- [cds-plugin](https://github.com/cap-js-community/event-queue/blob/main/cds-plugin.js): plugin entry · Auto-attaches the package to CAP applications · `cds-plugin.js`
- [Public API](https://github.com/cap-js-community/event-queue/blob/main/src/index.js): API surface · Exports the package API and runtime wiring · `src/index.js`

### Core runtime

Publishing, queue processing, scheduling, and lifecycle orchestration

- [Init](https://github.com/cap-js-community/event-queue/blob/main/src/initialize.js): bootstrap · Initializes plugin state and runtime wiring · `src/initialize.js`
- [Config](https://github.com/cap-js-community/event-queue/blob/main/src/config.js): settings · Resolves runtime configuration and constants · `src/config.js`
- [Publish](https://github.com/cap-js-community/event-queue/blob/main/src/publishEvent.js): enqueue · Turns application events into durable queue records · `src/publishEvent.js`
- [DB handler](https://github.com/cap-js-community/event-queue/blob/main/src/dbHandler.js): persistence adapter · Writes and reads queue state through CAP persistence · `src/dbHandler.js`
- [Process queue](https://github.com/cap-js-community/event-queue/blob/main/src/processEventQueue.js): consumer loop · Drives event consumption and execution lifecycle · `src/processEventQueue.js`
- [Processor base](https://github.com/cap-js-community/event-queue/blob/main/src/EventQueueProcessorBase.js): execution base · Shared processor abstraction for queue handlers · `src/EventQueueProcessorBase.js`
- [Periodic events](https://github.com/cap-js-community/event-queue/blob/main/src/periodicEvents.js): scheduler · Schedules recurring work onto the same queue model · `src/periodicEvents.js`

### Persistence

Database schema and durable queue tables

- [Event schema](https://github.com/cap-js-community/event-queue/blob/main/db/Event.cds): cds model · Defines the persisted event queue table · `db/Event.cds`
- [Lock schema](https://github.com/cap-js-community/event-queue/blob/main/db/Lock.cds): cds model · Defines coordination and locking tables · `db/Lock.cds`
- [DB index](https://github.com/cap-js-community/event-queue/blob/main/db/index.cds): cds model · Aggregates the queue schema for deployment · `db/index.cds`

### Coordination

Locking, runners, and Redis-assisted cross-instance coordination

- [Runner](https://github.com/cap-js-community/event-queue/blob/main/src/runner/runner.js): worker coordinator · Coordinates worker startup and queue polling · `src/runner/runner.js`
- [Open events](https://github.com/cap-js-community/event-queue/blob/main/src/runner/openEvents.js): dispatcher · Finds eligible events and hands them to workers · `src/runner/openEvents.js`
- [Distributed lock](https://github.com/cap-js-community/event-queue/blob/main/src/shared/distributedLock.js): coordination · Prevents duplicate processing across instances · `src/shared/distributedLock.js`
- [Redis pub](https://github.com/cap-js-community/event-queue/blob/main/src/redis/redisPub.js): pubsub · Publishes low-latency event notifications · `src/redis/redisPub.js`
- [Redis sub](https://github.com/cap-js-community/event-queue/blob/main/src/redis/redisSub.js): pubsub · Receives notifications and wakes polling workers · `src/redis/redisSub.js`
- [Redis client](https://github.com/cap-js-community/event-queue/blob/main/src/shared/redis/index.js): client layer · Shared Redis client and connection management · `src/shared/redis/index.js`

### Integrations

CAP outbox and service-facing adapters

- [Outbox adapter](https://github.com/cap-js-community/event-queue/blob/main/src/outbox/eventQueueAsOutbox.js): cap outbox · Adapts the queue to CAP outbox semantics · `src/outbox/eventQueueAsOutbox.js`
- [Outbox handler](https://github.com/cap-js-community/event-queue/blob/main/src/outbox/EventQueueGenericOutboxHandler.js): outbox handler · Implements generic outbox integration behavior · `src/outbox/EventQueueGenericOutboxHandler.js`
- [Admin service](https://github.com/cap-js-community/event-queue/blob/main/srv/service/admin-service.js): cap service · Exposes management and administration endpoints · `srv/service/admin-service.js`
- [Example app](https://github.com/cap-js-community/event-queue/blob/main/example-cap-server/srv/handler/process-service.js): demo cap app · Shows CAP service usage with queue-backed handlers · `example-cap-server/srv/handler/process-service.js`

### Ops

Housekeeping and runtime telemetry

- [Housekeeping](https://github.com/cap-js-community/event-queue/blob/main/src/housekeeping/EventQueueDeleteEvents.js): cleanup · Deletes old queue records after processing · `src/housekeeping/EventQueueDeleteEvents.js`

## Connections

- cds-plugin → Public API: loads · The plugin entry wires the public API into CAP
- Public API → Init: initializes · Public API bootstraps runtime setup
- Init → Config: reads · Initialization resolves configuration
- Publish → DB handler: persists · Published events are written through the DB handler
- DB handler → Event schema: stores · Event rows are stored in the queue table
- DB handler → Lock schema: coordinates · Lock state is stored alongside queue data
- DB index → Event schema: includes · Schema aggregation includes the event table
- DB index → Lock schema: includes · Schema aggregation includes the lock table
- Process queue → Processor base: executes via · Queue processing is built on the processor base
- Process queue → Open events: discovers · Processing asks runner logic for open events
- Open events → Distributed lock: claims · Open-event selection is protected by distributed locking
- Runner → Open events: orchestrates · The runner coordinates event discovery
- Runner → Redis pub: publishes · Runner path can react to Redis notifications
- Redis sub → Redis client: uses · Subscriber relies on shared Redis client management
- Redis pub → Redis client: uses · Publisher relies on shared Redis client management
- Periodic events → Process queue: enqueues · Periodic work is processed by the same queue engine
- Outbox adapter → Outbox handler: implements · Outbox adapter is backed by the generic handler
- Outbox adapter → Publish: publishes through · Outbox integration routes work into event publication
- Housekeeping → Event schema: cleans · Housekeeping deletes old event rows
- Admin service → Process queue: manages · Admin service observes or manages queue processing
- Example app → Outbox adapter: demonstrates · Example app shows outbox-style integration
- Example app → Publish: produces · Example services publish events into the queue
