← Back to Plugin Architecture

5.2 Awards Plugin

The Awards plugin owns the tenant-local path from award configuration and recommendations through approval, feedback, bestowal preparation, and court presentation. Its current architecture is service- and workflow-driven; the older single status-machine/Kanban description is no longer sufficient.

Domain areas

Area Main models
Catalog Domain, Level, Award, gathering-activity links
Recommendations Recommendation, state logs, groups, notes
Approval configuration ApprovalProcess, ApprovalProcessStep
Approval execution RecommendationApprovalRun, core workflow instances/approvals
Feedback Feedback requests, items, recipients, and AwardsFeedback approval context
Bestowals Bestowal, recommendation links, to-do templates/items, core ActionItems
Court planning CourtAgenda, segments, and items
Migration/audit Recommendation migration runs/results and reconciliation commands

Recommendation lifecycle

Submission and mutation go through dedicated services such as RecommendationSubmissionService, RecommendationUpdateService, RecommendationTransitionService, RecommendationDeletionService, and RecommendationStateLogService. Approval processes are configured per award, snapshotted into runs, and executed through versioned workflow definitions and canonical core approvals.

Grouping, feedback, hidden/private information, exports, and bestowal ownership each have specific policy/service rules. A recommendation linked to a bestowal is intentionally locked against incompatible mutation.

The current workflow definitions include submitted/updated/deleted events, grouping and ungrouping, existing-recommendation approval, and bestowal create/update/transition/cancel flows. Treat the JSON definitions and registered provider metadata as the orchestration source of truth.

Approval process synchronization

RecommendationApprovalWorkflowSyncService can restart eligible open recommendations for one selected approval process when their snapshot or published workflow version is outdated. It audit-cancels active runs/instances/pending gates and starts exactly one replacement per recommendation. Historical responses remain history and never count toward the replacement. Closed, approved, bestowal-owned, deleted, grouped-child, and otherwise ineligible recommendations are skipped.

Do not implement this as a bulk direct update; the per-recommendation transaction and bounded failure reporting are part of the contract.

Bestowals and action items

Bestowal services own creation, updates, transitions, handoff, cancellation, finalization, recommendation links, court slots, and notification variables. To-do templates materialize as core ActionItem records using stable item keys/source references. Synchronization preserves matching history, cancels removed items, converges prerequisite/required-field rules, and never implicitly finalizes a bestowal.

Given or cancelled bestowals reject queued ActionItem mutations. Finalization rechecks required work under the bestowal lock and audit-cancels remaining optional items as not applicable.

Extension and safety rules

References

Models and tables

Policies

Services and executable behavior