Version: 1.1

Shumoul Background Jobs Framework — Official Developer Guide

Version: 1.0.0 · Status: Golden Reference (execution/runtime) · Level 3 Certified · LTS · Initiative closed 2026-07-04 Classification: {{brand.classification.internal}}

This is the complete official documentation for the Shumoul Background Jobs Framework — the generic, host-agnostic recurring-job execution runtime used across the Shumoul Cloud ERP platform.

It is written for: Backend Developers, Platform Engineers, QA Engineers, Technical Partners, and Future Internal Developers extending or consuming the framework from a new host.

Every fact in this documentation is derived from the platform's existing, frozen architecture record — this guide transforms that record into developer-facing chapters; it does not redesign or reinterpret the architecture. Source material: docs/ARCHITECTURE/BACKGROUND_JOBS_*.md and docs/ARCHITECTURE/STANDARDS/ in the Shumoul.Saas.Api repository, the ADR set (docs/ARCHITECTURE/adr/ADR-003 through ADR-006), and the framework's own source at Shumoul.Saas.BackgroundJobsFramework. Where source documents disagreed with each other (a small number of internal counting inconsistencies — see Chapter 20 — Appendix § Verification Notes), this guide states the discrepancy explicitly rather than silently picking one version.

Relationship to the Notification Framework

The Background Jobs Framework is the platform's second Golden Reference module, and the first to certify the execution/runtime shape (the Notification Framework certified the data/delivery shape). The two are architectural siblings, not layers of one another: no package-level dependency exists in either direction. Where they meet is at the ERP host — every recurring job that used to belong to the Notification Framework's own Hangfire registrations (retry processor, retry expire, dead-letter cleanup, campaign scheduler, campaign workflow executor, campaign cleanup) now triggers through a Background Jobs Framework pipeline, which calls into an ERP-owned adapter, which calls the same, unchanged Notification Framework business service it always called. See Chapter 14 — Job Migration Guide.

#	Section	File
1	Overview	01-overview.md
2	Architecture	02-architecture.md
3	Packages	03-packages.md
4	Runtime Pipeline	04-runtime-pipeline.md
5	Execution Flow	05-execution-flow.md
6	Runtime Services	06-runtime-services.md
7	Adapters	07-adapters.md
8	Tenant Context	08-tenant-context.md
9	Distributed Lock	09-distributed-lock.md
10	Scheduler	10-scheduler.md
11	Execution Context	11-execution-context.md
12	Public API	12-public-api.md
13	Host Integration	13-host-integration.md
14	Job Migration Guide	14-job-migration-guide.md
15	Architecture Decisions	15-architecture-decisions.md
16	Testing	16-testing.md
17	Performance	17-performance.md
18	Troubleshooting	18-troubleshooting.md
19	FAQ	19-faq.md
20	Appendix	20-appendix.md

Relationship to the Notification Framework​

Table of Contents​

Relationship to the Notification Framework

Table of Contents