# PostFundManagement (PFM) Platform — Operational Processes & Governance (Processes.md)

> **Document Context**: Authoritative operational manual and process specification for the PFM Platform. Derived from the PFM SRS v2.0 and governing all lifecycle transitions, workflow gates, RBAC controls, and Maker-Checker segregation of duties.

---

## 1. PFM End-to-End Operational Lifecycle

The PFM platform governs the lifecycle of grant, development, innovation, and impact funding portfolios from the moment an award is approved through long-term post-fund monitoring.

```
┌────────────────────────────────────────────────────────────────────────────────────────┐
│                                 POST-FUND LIFECYCLE                                    │
│                                                                                        │
│  [1. Award Intake]  ──>  [2. Contracting]  ──>  [3. Onboarding]                        │
│   External Approval       Draft Agreement       KYC & Banking Gate                     │
│   Recorded (BR-001)       Auto-created (BR-002) Required for Disb. (BR-003)            │
│         │                                                                              │
│         ▼                                                                              │
│  [4. Project & WBS] ──>  [5. Budget & Lines] ──> [6. Disbursement Gate]                │
│   Milestones & Tasks      Allocations & Caps     Requires Verified Evidence            │
│   Progress Tracking       No Over-commitment     & Satisfied Conditions (BR-004)       │
│         │                                                                              │
│         ▼                                                                              │
│  [7. M&E & Evidence] ─>  [8. Change & Risk]  ──> [9. Close-Out & Impact]               │
│   Indicator Actuals       Variations & Issues    Post-Fund Monitoring                  │
│   Field Site Visits       Audit Trail (BR-007)   Portfolio Roll-Up (BR-010)            │
└────────────────────────────────────────────────────────────────────────────────────────┘
```

---

## 2. Core Operational Processes

### 2.1 Process 1: Award Intake & Funding Registration (Module M01)
* **Pre-condition**: Award has been approved by external sanctioning committee (BR-001).
* **Actor**: Funding Administrator (`grant_financials: add`).
* **Workflow**:
  1. Capture external reference number, award amount ($> 0$), funding period, programme, and recipient organisation.
  2. System enforces duplicate check against external reference numbers.
  3. Upon successful award creation, the system **automatically initializes** the corresponding legal `Contract` in `Draft` status (BR-002).

### 2.2 Process 2: Contracting & Agreement Management (Module M02)
* **Pre-condition**: Valid award record exists.
* **Actors**: Legal / Programme Manager (`grant_financials: add`), Executive / Authorised Signatory (`grant_financials: update`).
* **Workflow**:
  1. Author attaches legal terms, clauses, total value, and effective/expiry dates.
  2. Upload signed bilateral agreement PDF.
  3. Transition contract status to `Active`.
  4. **Maker-Checker Rule**: The user who uploaded or created the contract cannot be the signatory who transitions it to `Active`.

### 2.3 Process 3: Project WBS & Milestones Management (Module M04 & M07)
* **Pre-condition**: Project is in `Active` status.
* **Actors**: Contributor / Project Manager (`projects_milestones: add`), Supervisor / Manager (`projects_milestones: update`).
* **Workflow**:
  1. Project Manager defines contractual milestones with due dates and priority levels.
  2. Contributors log ground activities against milestones.
  3. Contributor uploads completion evidence.
  4. Status transitions from `Planned` $\to$ `In Progress` $\to$ `Submitted` $\to$ `Under Review` $\to$ `Verified & Approved`.
  5. **Verification Gate**: Only users with `projects_milestones: update` who **did not create** the milestone can verify and approve it.

### 2.4 Process 4: Disbursement Control & Payment Release (Module M05 & M06)
* **Pre-condition**: Recipient onboarding complete, banking details verified, and linked milestone deliverable verified.
* **Actors**: Finance Officer (`grant_financials: add`), Finance Director / Manager (`grant_financials: update`).
* **Workflow**:
  1. Finance Officer drafts disbursement tranche drawdown against verified milestone.
  2. System validates conditions precedent and budget caps (commits + expenditures $\le$ approved budget line).
  3. Authoriser verifies evidence and approves tranche release.
  4. **Maker-Checker Rule**: The user who captured the payment request cannot approve the disbursement.

### 2.5 Process 5: M&E Indicators, Risks & Evidence Review (Module M08 & M09)
* **Pre-condition**: Approved project indicators and risk registers configured.
* **Actors**: M&E Officer (`evidence_risks: add`), Programme Supervisor (`evidence_risks: update`).
* **Workflow**:
  1. Field staff or recipients submit indicator actuals and supporting verification files (`EvidenceType`).
  2. Evidence enters the `EvidenceReviewQueue`.
  3. Supervisor reviews document authenticity, geotags, and deliverable match.
  4. Decision: `Approve & Verify` or `Reject` (with mandatory rework reasoning).
  5. **Maker-Checker Rule**: The officer who uploaded the evidence document cannot approve their own submission.

### 2.6 Process 6: Change Management & Variations (Module M15 & M16)
* **Pre-condition**: Active project with identified issue or required contractual variance.
* **Actors**: Contributor (`change_management: add`), Manager (`change_management: update`).
* **Workflow**:
  1. Contributor logs project issue or drafts contractual change request (budget reallocation, timeline extension, scope shift).
  2. Impact assessment conducted.
  3. Governance deliberation.
  4. Resolution: `Approved & Enacted` or `Rejected`.
  5. **Maker-Checker Rule**: Change request initiator cannot approve or enact the change.

### 2.7 Process 7: Automated Background Workflows & Scheduled Jobs (PostFundManagement.Jobs)
* **Pre-condition**: Background jobs host (`PostFundManagement.Jobs`) active and connected to `pfm-scheduler`.
* **Actors**: System Engine, `JobsWorker` Daemon, Domain Event Handlers.
* **Workflow**:
  1. **Event Triggering**: API operations emit strongly typed events (`IEvent`) and enqueue them into `pfm-scheduler` via `IJobOrchestrator`.
  2. **Cron Schedule Execution**: `JobsWorker` initializes recurring schedules on daemon startup for periodic monitoring, risk assessments, and communication batches.
  3. **Job Execution**: Quartz cluster dispatches acquired triggers to `MediatorJob<TNotification>` within `PostFundManagement.Jobs` (concurrency limit = 5).
  4. **Mediated Processing**: Event payload is deserialized and published via `IMediator` to execute domain logic (project monitoring, risk threshold checks, email dispatch).
  5. **Cascading One-Time Jobs**: When a recurring job identifies an action item requiring separate asynchronous execution, it triggers a decoupled one-time job (`jobOrchestrator.SendAsync`).

---

## 3. The Maker-Checker Operational Policy

### 3.1 Policy Definition
Under PFM enterprise governance standards, **dual authorization (Maker-Checker)** is mandatory for all material lifecycle decisions:

$$\text{Approval Granted} \iff (\text{User has 'update' permission}) \land (\text{User ID} \neq \text{Record Creator ID})$$

### 3.2 Matrix of Segregated Actions

| Operational Domain | Maker Action (`add`) | Checker Action (`update`) | Maker-Checker Invariant |
| :--- | :--- | :--- | :--- |
| **Projects & Governance** | Register project, update scope | Approve project governance status | Creator cannot approve project |
| **Contractual Milestones** | Define milestone, submit evidence | Verify deliverable, approve milestone | Milestone author cannot verify |
| **Disbursements** | Capture tranche drawdown request | Authorize payment release | Requestor cannot release payment |
| **Budgets** | Define budget line, allocate funds | Approve statutory budget line | Allocator cannot approve budget |
| **Evidence Queue** | Upload proof, ingest documentation | Approve & verify evidence artifact | Submitter cannot verify evidence |
| **Change Requests** | Draft scope / budget variation | Approve & enact variation | Initiator cannot enact change |
| **Site Visits** | Log field checklist & observations | Approve site inspection report | Inspector cannot self-sign report |
| **Programmes** | Create programme structure | Approve programme governance | Creator cannot approve programme |

### 3.3 System Behavior on Maker-Checker Collisions
When an authorised approver navigates to a record they personally created:
1. **Dropdown Controls**: The `Approved` option is disabled with the label:  
   `Approved (Maker-Checker: Cannot approve own record)`
2. **Action Buttons**: Fast-track approve buttons are hidden, and a visual tag `Maker-Checker (Creator)` is displayed.
3. **Audit Trail**: Any attempt to bypass client controls logs a security violation in the immutable audit log (`settings_auditlog`).

---

## 4. RBAC Operational Roles & Boundaries

### 4.1 Role Assignment Rules
1. **`Contributor`**: Operational field execution. Strictly restricted to `view` and `add`. Contributors can create activities, submit evidence, and draft change requests, but **never approve records or export datasets**.
2. **`Supervisor`**: Operational oversight. Possesses `view, add, update, export`. Verifies milestones, inspects evidence, reviews site visits, and exports reports, subject to the Maker-Checker rule.
3. **`Manager`**: Comprehensive operational management. Possesses `all` across operational domains. Manages audit logs, notifications, and tenancy.
4. **`Executive`**: Strategic leadership. Possesses `all` across strategic domains (`dashboard`, `governance`, `grant_financials`, `evidence_risks`).
5. **`Admin`**: System administrator. Possesses `unrestricted: all`. Governs tenant boundaries, partitions, and system security.
6. **`Partner`**: External grantee / recipient. Strictly confined to `PartnerUI`. Any attempt to access `ConsoleUI` triggers an immediate security lockout.

---

## 5. Caching & Mutation Invalidation Workflow

To ensure that caching never impedes record lifecycle updates or displays stale data while maximizing UI responsiveness, the following operational flow is enforced across ConsoleUI:

```mermaid
sequenceDiagram
    autonumber
    actor User as User / Maker
    participant UI as ConsoleUI React Query
    participant Client as Axios HttpClient
    participant OutputCache as Backend OutputCache Redis/Memory
    participant DB as PostgreSQL Database

    User->>UI: Submits Record Mutation Create/Update/Approve
    UI->>Client: Dispatches POST / PUT / PATCH / DELETE
    Client->>DB: Executes Mutation in Database
    DB-->>Client: Returns 200 OK / 201 Created
    Client->>Client: Interceptor detects mutation: bumps activeMutationEpoch
    UI->>UI: onSuccess triggers invalidateQueries
    UI->>Client: Refetches active queries with _v = activeMutationEpoch
    Client->>OutputCache: GET /v1/api/* with new _v epoch
    Note over OutputCache: Cache Miss: new _v key never seen before
    OutputCache->>DB: Queries PostgreSQL for fresh data
    DB-->>OutputCache: Returns updated entities
    OutputCache-->>UI: Caches fresh data under _v and returns to UI
    UI-->>User: UI updates immediately with new status / record
```

### 5.1 Operating Rules for Record Modifications
1. **Zero Manual Cache Eviction Required**: Frontend developers do not need to manually configure cache busters for standard operations. The Axios response interceptor in `httpClient.ts` automatically increments `activeMutationEpoch` on any successful mutating call (`POST`, `PUT`, `PATCH`, `DELETE`).
2. **Deterministic Invalidation**: Calling standard `queryClient.invalidateQueries({ queryKey: [...] })` or `invalidateAndBustCache(queryClient, filters)` guarantees that the subsequent refetch bypasses stale ASP.NET Core OutputCache entries.
3. **Optimized Read Cache**: When users navigate across unchanged views or switch tabs, identical `_v` tokens are reused, allowing backend OutputCache and React Query in-memory caches to fulfill requests in < 5ms without unnecessary database hits.

---

## 6. Background Job Lifecycle & Event Execution Workflows

The dedicated worker host (`PostFundManagement.Jobs`) operates as a decoupled daemon executing recurring maintenance routines and asynchronous domain events dispatched from the API or internally from other jobs.

### 6.1 Event Ingestion & Job Persistence Flow

```mermaid
flowchart TD
    subgraph Producer ["PostFundManagement.Api (Event Source)"]
        A["User Action / Lifecycle Transition"] --> B["Domain Command / Mutation"]
        B --> C["Instantiate IEvent (e.g. SyncUserEvent, ProjectReminderEvent)"]
        C --> D["IJobOrchestrator.SendAsync() or ScheduleAsync()"]
    end

    subgraph Store ["PostgreSQL Clustered Store (pfm-scheduler)"]
        D --> E[("QRTZ_JOB_DETAILS and QRTZ_TRIGGERS")]
    end

    subgraph Consumer ["PostFundManagement.Jobs (Execution Host)"]
        E -->|"Acquire Trigger Lock"| F["Quartz Scheduler Engine (MaxConcurrency = 5)"]
        F --> G["MediatorJob[TNotification]"]
        G --> H["Deserialize JSON Payload from JobDataMap"]
        H --> I["IMediator.Publish(notification)"]
        I --> J["Domain Event Handler: Business Logic in pfm DB"]
        J -.->|"Cascading Sub-Task Needed"| K["IJobOrchestrator.SendAsync: Dispatch One-Time Job"]
        K -.-> E
    end
```

### 6.2 Standard Background Processes

#### 1. Automated Project Monitoring & Reminders Process
* **Trigger**: Scheduled cron job registered on `JobsWorker` startup.
* **Operational Cycle**:
  1. Job queries active projects and non-completed milestones across tenant partitions.
  2. Compares milestone contractual due dates against current UTC time:
     - **T - 14 / T - 7 / T - 1 Days**: Emits reminder notification events to Grantee/Partner project managers.
     - **T + 0 Days (Overdue)**: Automatically flags the milestone as `Overdue` (`FR-M07-009`) and updates project RAG status to `At Risk` (`FR-M04-017`).
  3. Escalates overdue notifications to internal Programme Managers for intervention.

#### 2. Risk Monitoring & Automated Escalation Process
* **Trigger**: Periodic recurring schedule.
* **Operational Cycle**:
  1. Queries all active project risk registers and Key Risk Indicators (KRIs) (`FR-M09-001` - `011`).
  2. Evaluates current severity score ($\text{Risk Score} = \text{Likelihood} \times \text{Impact}$).
  3. If risk score breaches the configured programme tolerance threshold:
     - Automatically logs a risk escalation event.
     - Dispatches alerts to Risk Managers and Portfolio Executives.
  4. Sweeps assigned risk mitigation actions; identifies overdue mitigation plans and emits reminders to responsible assignees.

#### 3. Email Notification Processing Workflow (`Platform.Email`)
* **Trigger**: High-frequency recurring polling job or deferred one-time dispatch.
* **Operational Cycle**:
  1. Queries pending notifications from the transactional database where `Platform == NotificationPlatform.Email` and `Status == NotificationStatus.Pending` or `Queued`.
  2. Resolves tenant context using `HeadlessTenantContextService`.
  3. Formats email templates with recipient credentials and branding.
  4. Transmits messages via MailKit/MimeKit SMTP engine with rate-limiting and connection pooling.
  5. On successful delivery: Updates record status to `Sent`, stamps `DeliveredAt` timestamp, and logs dispatch telemetry (`FR-M25-001`).
  6. On failure: Increments retry counter; if retry limit exceeded, marks as `Failed` with diagnostic error trace.

### 6.3 Recurring-to-One-Time Job Cascading Pattern

When a recurring job evaluates a broad batch of records (e.g., scanning thousands of project indicators or verifying compliance expirations), it must not execute long-running operations synchronously in the recurring job thread:
1. The recurring job identifies items requiring heavy processing (e.g. generating an executive PDF digest or calling external webhooks).
2. For each identified item, it enqueues an isolated one-time job via `IJobOrchestrator.SendAsync(specificEvent)`.
3. This releases the recurring job quickly, distributes execution across the 5 available worker threads in `PostFundManagement.Jobs`, and guarantees that a single failed sub-task can be retried independently without stalling the entire recurring cycle.