168 lines
12 KiB
Markdown
168 lines
12 KiB
Markdown
# 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:
|
|
|
|
```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 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.
|
|
|
|
|