pfm/Processes.md

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.

---

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:

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 queryClient.invalidateQueries()
    UI->>Client: Refetches active queries with _v = activeMutationEpoch
    Client->>OutputCache: GET /v1/api/*?_v=<newEpoch>
    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.