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.
Table of Contents
| # | 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 |