# mavulahq/workbench architecture

> Architecture diagram of the GitHub repository mavulahq/workbench, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-11). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/mavulahq/workbench
- Repository: https://github.com/mavulahq/workbench

## Overview

MAVULA Workbench is a durable BullMQ worker runtime and public platform-status API. The main path is an authenticated client submitting or querying jobs, the API persisting them, and queue consumers dispatching work to payment, legacy-batch, or Ledger Core callback handling. Scheduling, settlement-outbox publishing, and health/metrics are separate runtime capabilities. The excerpts establish the main dispatch and monitoring calls; README documents broader scheduling and retry behavior, while several implementation details and integrations were not sampled.

Main entry points: [`src/status/platform-status.service.ts`](https://github.com/mavulahq/workbench/blob/main/src/status/platform-status.service.ts) (Platform Health), [`src/queue/job-store.service.ts`](https://github.com/mavulahq/workbench/blob/main/src/queue/job-store.service.ts) (Job Store), [`src/worker/job-handlers.service.ts`](https://github.com/mavulahq/workbench/blob/main/src/worker/job-handlers.service.ts) (Job Dispatch), [`src/worker/worker-metrics.service.ts`](https://github.com/mavulahq/workbench/blob/main/src/worker/worker-metrics.service.ts) (Worker Metrics)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["Public API"]
  node_jobs_api["Jobs API<br/>[jobs.controller.ts]"]
  node_legacy_api["Legacy Batch API"]
  node_status_api["Status API"]
  node_auth["Access Control"]
end

subgraph group_queue["Queue Runtime"]
  node_job_store[("Job Store")]
  node_worker["Queue Consumers<br/>[worker.service.ts]"]
  node_scheduler["Job Scheduler"]
  node_scheduler_capabilities["Fee, Interest, Reconciliation, Reports"]
end

subgraph group_processing["Job Processing"]
  node_handlers["Job Dispatch"]
  node_payment_runtime[("Payment Processes")]
  node_legacy_runtime[("Legacy Batches")]
  node_service_tokens["Service Tokens"]
  node_outbox["Settlement Publisher"]
end

subgraph group_operations["Operations"]
  node_status_service["Platform Health"]
  node_metrics["Worker Metrics"]
  node_runtime_config["Runtime Config<br/>[runtime-config.ts]"]
end

node_client(("API Client"))
node_ledger_core["Ledger Core"]
node_database[("Postgres")]
node_redis[("Redis")]
node_prometheus(("Prometheus Scraper"))

node_client -->|"submits jobs"| node_jobs_api
node_client -->|"manages batches"| node_legacy_api
node_client -->|"checks status"| node_status_api
node_jobs_api -->|"requires permissions"| node_auth
node_jobs_api -->|"enqueues and reads"| node_job_store
node_legacy_api -->|"uses queue store"| node_job_store
node_legacy_api -->|"manages batches"| node_legacy_runtime
node_worker -->|"claims and completes"| node_job_store
node_worker -->|"dispatches jobs"| node_handlers
node_handlers -->|"handles payments"| node_payment_runtime
node_handlers -->|"handles legacy jobs"| node_legacy_runtime
node_handlers -->|"requests tenant token"| node_service_tokens
node_handlers -->|"calls worker APIs"| node_ledger_core
node_service_tokens -->|"obtains access token"| node_ledger_core
node_scheduler -->|"schedules jobs"| node_job_store
node_scheduler_capabilities -.->|"scheduled by"| node_scheduler
node_outbox -->|"publishes settlement events"| node_payment_runtime
node_outbox -.->|"publishes callbacks"| node_ledger_core
node_status_api -->|"serves health"| node_status_service
node_status_service -->|"reads queue stats"| node_job_store
node_status_service -->|"checks runtime"| node_worker
node_status_service -->|"lists schedules"| node_scheduler
node_status_service -->|"reads metrics"| node_metrics
node_status_service -->|"checks dependency"| node_ledger_core
node_status_service -->|"checks TCP health"| node_database
node_status_service -->|"checks queue health"| node_redis
node_metrics -->|"reads queue stats"| node_job_store
node_metrics -->|"reads worker state"| node_worker
node_metrics -->|"reads payment metrics"| node_payment_runtime
node_metrics -->|"reads batch metrics"| node_legacy_runtime
node_prometheus -.->|"scrapes metrics"| node_status_api
node_runtime_config -->|"configures backend"| node_job_store
node_runtime_config -->|"configures workers"| node_worker
node_runtime_config -->|"configures schedules"| node_scheduler

click node_jobs_api "https://github.com/mavulahq/workbench/blob/main/src/controllers/jobs.controller.ts"
click node_legacy_api "https://github.com/mavulahq/workbench/blob/main/src/controllers/legacy-batches.controller.ts"
click node_status_api "https://github.com/mavulahq/workbench/blob/main/src/controllers/status.controller.ts"
click node_auth "https://github.com/mavulahq/workbench/blob/main/src/auth/access-token.guard.ts"
click node_job_store "https://github.com/mavulahq/workbench/blob/main/src/queue/job-store.service.ts"
click node_worker "https://github.com/mavulahq/workbench/blob/main/src/worker/worker.service.ts"
click node_scheduler "https://github.com/mavulahq/workbench/blob/main/src/worker/scheduler.service.ts"
click node_handlers "https://github.com/mavulahq/workbench/blob/main/src/worker/job-handlers.service.ts"
click node_payment_runtime "https://github.com/mavulahq/workbench/blob/main/src/worker/payment-process-runtime.service.ts"
click node_legacy_runtime "https://github.com/mavulahq/workbench/blob/main/src/worker/legacy-batch-runtime.service.ts"
click node_service_tokens "https://github.com/mavulahq/workbench/blob/main/src/auth/service-token.service.ts"
click node_outbox "https://github.com/mavulahq/workbench/blob/main/src/worker/payment-outbox-publisher.service.ts"
click node_status_service "https://github.com/mavulahq/workbench/blob/main/src/status/platform-status.service.ts"
click node_metrics "https://github.com/mavulahq/workbench/blob/main/src/worker/worker-metrics.service.ts"
click node_runtime_config "https://github.com/mavulahq/workbench/blob/main/src/utils/runtime-config.ts"
click node_scheduler_capabilities "https://github.com/mavulahq/workbench/blob/main/src/worker/scheduler.service.ts"

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_jobs_api,node_legacy_api,node_status_api,node_auth,node_client toneBlue
class node_job_store,node_worker,node_scheduler,node_scheduler_capabilities,node_database,node_redis toneAmber
class node_handlers,node_payment_runtime,node_legacy_runtime,node_service_tokens,node_outbox toneMint
class node_status_service,node_metrics,node_runtime_config toneRose
class node_ledger_core,node_prometheus toneIndigo
```

## Components

### Public API

- [Jobs API](https://github.com/mavulahq/workbench/blob/main/src/controllers/jobs.controller.ts): `src/controllers/jobs.controller.ts`
- [Legacy Batch API](https://github.com/mavulahq/workbench/blob/main/src/controllers/legacy-batches.controller.ts): `src/controllers/legacy-batches.controller.ts`
- [Status API](https://github.com/mavulahq/workbench/blob/main/src/controllers/status.controller.ts): `src/controllers/status.controller.ts`
- [Access Control](https://github.com/mavulahq/workbench/blob/main/src/auth/access-token.guard.ts): `src/auth/access-token.guard.ts`

### Queue Runtime

- [Job Store](https://github.com/mavulahq/workbench/blob/main/src/queue/job-store.service.ts): `src/queue/job-store.service.ts`
- [Queue Consumers](https://github.com/mavulahq/workbench/blob/main/src/worker/worker.service.ts): `src/worker/worker.service.ts`
- [Job Scheduler](https://github.com/mavulahq/workbench/blob/main/src/worker/scheduler.service.ts): `src/worker/scheduler.service.ts`
- [Fee, Interest, Reconciliation, Reports](https://github.com/mavulahq/workbench/blob/main/src/worker/scheduler.service.ts): `src/worker/scheduler.service.ts`

### Job Processing

- [Job Dispatch](https://github.com/mavulahq/workbench/blob/main/src/worker/job-handlers.service.ts): `src/worker/job-handlers.service.ts`
- [Payment Processes](https://github.com/mavulahq/workbench/blob/main/src/worker/payment-process-runtime.service.ts): `src/worker/payment-process-runtime.service.ts`
- [Legacy Batches](https://github.com/mavulahq/workbench/blob/main/src/worker/legacy-batch-runtime.service.ts): `src/worker/legacy-batch-runtime.service.ts`
- [Service Tokens](https://github.com/mavulahq/workbench/blob/main/src/auth/service-token.service.ts): `src/auth/service-token.service.ts`
- [Settlement Publisher](https://github.com/mavulahq/workbench/blob/main/src/worker/payment-outbox-publisher.service.ts): `src/worker/payment-outbox-publisher.service.ts`

### Operations

- [Platform Health](https://github.com/mavulahq/workbench/blob/main/src/status/platform-status.service.ts): `src/status/platform-status.service.ts`
- [Worker Metrics](https://github.com/mavulahq/workbench/blob/main/src/worker/worker-metrics.service.ts): `src/worker/worker-metrics.service.ts`
- [Runtime Config](https://github.com/mavulahq/workbench/blob/main/src/utils/runtime-config.ts): `src/utils/runtime-config.ts`

### Other components

- **API Client**
- **Ledger Core**
- **Postgres**
- **Redis**
- **Prometheus Scraper**

## Connections

- API Client → Jobs API: submits jobs (evidence: `src/controllers/jobs.controller.ts`)
- API Client → Legacy Batch API: manages batches (evidence: `src/controllers/legacy-batches.controller.ts`)
- API Client → Status API: checks status (evidence: `src/controllers/status.controller.ts`)
- Jobs API → Access Control: requires permissions (evidence: `src/controllers/jobs.controller.ts`)
- Jobs API → Job Store: enqueues and reads (evidence: `src/controllers/jobs.controller.ts`)
- Legacy Batch API → Job Store: uses queue store (evidence: `src/controllers/legacy-batches.controller.ts`)
- Legacy Batch API → Legacy Batches: manages batches (evidence: `src/controllers/legacy-batches.controller.ts`)
- Queue Consumers → Job Store: claims and completes (evidence: `src/worker/worker.service.ts`)
- Queue Consumers → Job Dispatch: dispatches jobs (evidence: `src/worker/worker.service.ts`)
- Job Dispatch → Payment Processes: handles payments (evidence: `src/worker/job-handlers.service.ts`)
- Job Dispatch → Legacy Batches: handles legacy jobs (evidence: `src/worker/job-handlers.service.ts`)
- Job Dispatch → Service Tokens: requests tenant token (evidence: `src/worker/job-handlers.service.ts`)
- Job Dispatch → Ledger Core: calls worker APIs (evidence: `src/worker/job-handlers.service.ts`)
- Service Tokens → Ledger Core: obtains access token (evidence: `src/auth/service-token.service.ts`)
- Job Scheduler → Job Store: schedules jobs (evidence: `src/worker/scheduler.service.ts`)
- Fee, Interest, Reconciliation, Reports → Job Scheduler: scheduled by (evidence: `README.md`)
- Settlement Publisher → Payment Processes: publishes settlement events (evidence: `src/worker/payment-outbox-publisher.service.ts`)
- Settlement Publisher → Ledger Core: publishes callbacks
- Status API → Platform Health: serves health (evidence: `src/controllers/status.controller.ts`)
- Platform Health → Job Store: reads queue stats (evidence: `src/status/platform-status.service.ts`)
- Platform Health → Queue Consumers: checks runtime (evidence: `src/status/platform-status.service.ts`)
- Platform Health → Job Scheduler: lists schedules (evidence: `src/status/platform-status.service.ts`)
- Platform Health → Worker Metrics: reads metrics (evidence: `src/status/platform-status.service.ts`)
- Platform Health → Ledger Core: checks dependency (evidence: `src/status/platform-status.service.ts`)
- Platform Health → Postgres: checks TCP health (evidence: `src/status/platform-status.service.ts`)
- Platform Health → Redis: checks queue health (evidence: `src/status/platform-status.service.ts`)
- Worker Metrics → Job Store: reads queue stats (evidence: `src/worker/worker-metrics.service.ts`)
- Worker Metrics → Queue Consumers: reads worker state (evidence: `src/worker/worker-metrics.service.ts`)
- Worker Metrics → Payment Processes: reads payment metrics (evidence: `src/worker/worker-metrics.service.ts`)
- Worker Metrics → Legacy Batches: reads batch metrics (evidence: `src/worker/worker-metrics.service.ts`)
- Prometheus Scraper → Status API: scrapes metrics
- Runtime Config → Job Store: configures backend (evidence: `src/queue/job-store.service.ts`)
- Runtime Config → Queue Consumers: configures workers (evidence: `src/worker/worker.service.ts`)
- Runtime Config → Job Scheduler: configures schedules (evidence: `src/worker/scheduler.service.ts`)