# PostFundManagement (PFM) Platform

An enterprise system designed to manage the entire post-funding grant and project lifecycle. PFM provides end-to-end oversight across strategic portfolios, programme allocation, project execution tracking, financial disbursements, monitoring & evaluation (M&E), and candidate notifications.

---

## 🏛️ System Architecture & Domain Model

The application follows a modular, hierarchical architecture where high-level funding directives cascade into measurable project outcomes and evidence verification.

```text
[Portfolios] ───> [Programmes] ───> [Projects] ───> [Awards] ───> [Contracts] ───> [Beneficiaries] ──> [Outcomes]
│               │               │
▼               │               ▼
[Rules]            ├─> [Milestones] ──> [Activities] ──> [Evidences]
                   ├─> [Disbursements]
                   ├─> [Indicators]
                   ├─> [Risks] & [Issues]
                   └─> [SiteVisits] & [ComplianceItems]
```

### **1. Portfolio & Programme Governance**
* **Portfolios**: Top-level containers for strategic investment themes.
* **Programmes**: Direct implementation vehicles linked to specific financial instruments (`Instruments`) and operational guidelines (`Rules`).

### **2. Project Execution & Monitoring**
* **Projects**: Central operational units categorized by `IndustrySector` and `ProjectType`.
* **Milestones & Activities**: Project progress is tracked through structured milestones. Project Managers author `Activities` against specific milestones to log ground work.
* **Risks, Issues & Compliance**: Managed via dedicated tracking logs (`Risks`, `Issues`, `ComplianceItems`, `ChangeRequests`) to maintain project integrity.

### **3. Grants, Contracting & Disbursements**
* **Awards & Contracts**: Binding grant agreements signed with target `Organisations`.
* **Beneficiaries & Outcomes**: Social and economic impact measurement down to individual beneficiary groups.
* **Disbursements**: Milestone-gated tranche releases tied to approved evidence and verification audits.

### **4. Monitoring, Evaluation & Evidence (M&E)**
* **Indicators**: KPI baseline, target, and actual metrics tracking.
* **Evidences**: Verifiable artifacts (`EvidenceType`) uploaded alongside activities, indicators, or milestones.
* **Site Visits**: Independent audit logs (`SiteVisits`) submitted by field inspectors.

### **5. Notifications & Platform Services**
* Multi-channel delivery engine (`NotificationPlatform`) tracking candidate invitations, reminders, and status updates (`NotificationStatus`) across Email, SMS, WhatsApp, In-App, and Webhooks.

### **6. Background Processing & Distributed Jobs Engine**
* **`PostFundManagement.Jobs`**: Dedicated background execution host powered by **Quartz.NET (v4.6+)** with a PostgreSQL clustered JobStore (`pfm-scheduler`).
* **Decoupled Architecture**: `PostFundManagement.Api` serves strictly as a scheduler client (`ZeroSizeThreadPool`), dispatching events into the cluster while leaving execution exclusively to `PostFundManagement.Jobs` (`MaxConcurrency = 5`).
* **Event-Driven Execution**: Domain events implementing `IEvent : INotification` are mediated and serialized into `MediatorJob<TNotification>`.
* **Core Automated Operations**:
  - **Automated Project Monitoring & Reminders**: Tracks milestones, evaluates planned vs actual deadlines, flags overdue statuses, and emits reminders to Grantees/Partners.
  - **Risk Monitoring & Automated Notifications**: Evaluates risk registers, tracks Key Risk Indicators (KRIs), flags score creep, and escalates overdue mitigation actions.
  - **Email Processing**: Asynchronously processes `NotificationPlatform.Email` records via MailKit/MimeKit SMTP.
  - **Recurring & Cascading Jobs**: `JobsWorker` registers recurring cron schedules on startup and can trigger isolated one-time jobs when sub-activities cannot be executed directly by another job.

---

## 🧩 Key System Enums

| Enum | Scope | Purpose |
| :--- | :--- | :--- |
| `IndustrySector` | Project Domain | Standardizes reporting across sectors (e.g., ICT, Agriculture, Manufacturing). |
| `ProjectType` | Project Domain | Classifies project scope (e.g., R&D, Infrastructure, Capacity Building). |
| `EvidenceType` | M&E / Verification | Categorizes uploaded proof (e.g., Attendance Register, Geotagged Photo, Bank Statement). |
| `NotificationPlatform` | System / Comms | Outlines dispatch channels (Email, SMS, WhatsApp, Push, Webhooks). |
| `NotificationStatus` | System / Comms | Tracks communication lifecycle (Pending, Queued, Sent, Delivered, Failed). |

---

## 🛠️ Tech Stack & Patterns

* **Backend Framework**: .NET 10.0 (C# 13) Web API / Minimal APIs
* **Frontend Portals**:
  * `PostFundManagement.ConsoleUI`: Internal Staff & Portfolio Administration Portal (React 19 + TypeScript + Vite + Tailwind CSS)
  * `PostFundManagement.PartnerUI`: External Recipient & Grantee Portal (React 19 + TypeScript + Vite + WebGL OGL)
* **Database**: PostgreSQL 14+ with Npgsql & EF Core 10
* **Security & Authentication**: Duende IdentityServer / OIDC PKCE + Claim-Based RBAC
* **Governance Patterns**: Maker-Checker Pattern (Dual Authorization & Segregation of Duties)
* **Architecture**: Clean Architecture / Domain-Driven Design (DDD) with CQRS (`Mediator`)
* **Object Storage**: S3-compatible storage (Garage S3 / AWS S3)
* **Caching & OutputCache Invalidation**: Redis StackExchange + ASP.NET Core `OutputCaching` (2-minute base policy) coupled with TanStack Query v5 and Axios client-side mutation versioning (`_v` parameter) for instantaneous reads and guaranteed zero-staleness on mutations
* **Telemetry**: OpenTelemetry Metrics, Traces & Logs with Aspire / OTLP
* **Distributed Background Jobs**: Quartz.NET 4.6+ with clustered PostgreSQL JobStore (`pfm-scheduler`), separating the API (Scheduler Client with `ZeroSizeThreadPool`) from `PostFundManagement.Jobs` (Worker Execution Daemon with `MaxConcurrency = 5`)

---

## 🔒 Role-Based Access Control (RBAC) & Maker-Checker Pattern

The platform implements strict governance invariants across all operational domains:

### 1. Progressive Action Hierarchy
* **`view`**: Read-only inspection of entity lists, details, and metrics.
* **`add`**: Create new records, edit drafts, submit evidence, and adjust non-approval statuses.
* **`update`**: Authoritative record **approval** authority (`Approved`, `Active` contracts).
* **`export`**: Export tabular data and reports (`.xlsx`, `.pdf`).
* **`all`**: Comprehensive authority across the claim domain.

### 2. Role Claim Matrix
* **`Admin`**: `unrestricted: all` — Full system-wide administration.
* **`Executive`**: Strategic oversight across Dashboard, Governance, Projects, Grants, M&E (`all`).
* **`Manager`**: Comprehensive operational control across all domains (`all`).
* **`Supervisor`**: Operational oversight and verification (`view, add, update, export`).
* **`Contributor`**: Working-level execution (`view, add`). Strictly barred from record approvals and exports.
* **`Partner`**: External recipient. Confined strictly to `PartnerUI`; locked out of `ConsoleUI`.

### 3. Maker-Checker Segregation of Duties
To eliminate conflicts of interest, record creators ("Makers") cannot approve ("Check") their own records. Even if an officer possesses the `update` claim, the system dynamically blocks self-approval on any record matching their `createdBy` identifier:
$$\text{Can Approve} = \text{Has 'update' permission} \land (\text{Current User ID} \neq \text{Record Creator ID})$$

For in-depth architectural and operational specifications, see:
* [Architecture.md](file:///c:/Users/Admin/source/repos/PostFundManagement/Architecture.md)
* [Processes.md](file:///c:/Users/Admin/source/repos/PostFundManagement/Processes.md)
* [GEMINI.md](file:///c:/Users/Admin/source/repos/PostFundManagement/GEMINI.md)

---

## 📁 Solution Structure

```text
PostFundManagement/
 ├── PostFundManagement.Domain/          # Core Domain Entities, Enums, Value Objects & Abstractions (IEvent)
 ├── PostFundManagement.Infrastructure/  # EF Core 10, PostgreSQL (Npgsql), Migrations, Data Protection
 ├── PostFundManagement.Application/     # CQRS Handlers, Mediator, DTOs, Validations, S3, Email, Job Orchestrator
 ├── PostFundManagement.Api/             # ASP.NET Core Minimal APIs / Carter, Auth (OIDC), Swagger/Scalar, Versioning
 ├── PostFundManagement.Jobs/            # Dedicated Quartz.NET Background Worker Host (Recurring & Event-Driven Jobs)
 ├── PostFundManagement.Tests/           # Unit & Integration Test Suite (xUnit, Coverlet)
 ├── PostFundManagement.ConsoleUI/       # Internal Staff & Admin Web Portal (React 19 + Vite + Tailwind 4)
 ├── PostFundManagement.PartnerUI/       # External Grantee / Recipient Portal (React 19 + Vite + WebGL OGL)
 ├── Architecture.md                     # System Architecture, Security, RBAC, Caching & Quartz Spec
 ├── Processes.md                        # Operational Grant Lifecycle, Maker-Checker & Background Workflows
 ├── GEMINI.md                           # Master Technical & Architecture Roadmap (SRS v2.0 Alignment)
 └── docker-compose.yml                  # Container orchestration for API and Frontends
```

## 🚀 Getting Started

### Prerequisites

* .NET 10.0 SDK or higher
* Node.js 20+ & Yarn (`yarn.lock` authoritative)
* PostgreSQL 14+

## Setup & Execution

### 1. Clone Repository:

```bash
git clone https://github.com/your-org/PostFundManagement.git
cd PostFundManagement
```

### 2. Configure Database Connection:
Update `appsettings.Development.json` in the API project with your local PostgreSQL details:

```json
{
  "ConnectionStrings": {
    "DefaultConnection": "Host=localhost;Database=pfm_db;Username=postgres;Password=your_password"
  }
}
```

### 3. Launch Backend API:

```bash
dotnet run --project PostFundManagement.Api
```

### 4. Launch ConsoleUI Frontend:

```bash
cd PostFundManagement.ConsoleUI
yarn install
yarn dev
```

## 📄 License

Internal Proprietary Software — All rights reserved.