165 lines
8.0 KiB
Markdown
165 lines
8.0 KiB
Markdown
# 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.
|
|
|
|
---
|
|
|
|
## 🧩 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
|
|
|
|
---
|
|
|
|
## 🔒 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 & Interfaces
|
|
├── PostFundManagement.Infrastructure/ # EF Core 10, PostgreSQL, Skoruba STS, Migrations
|
|
├── PostFundManagement.Application/ # CQRS Handlers, DTOs, Business Rules & Validations
|
|
├── PostFundManagement.Api/ # REST Endpoints, Middleware, Auth & Swagger/Scalar
|
|
├── PostFundManagement.Tests/ # Unit & Integration Test Suite
|
|
├── PostFundManagement.ConsoleUI/ # Internal Staff & Admin Web Portal (React 19 + Vite)
|
|
├── PostFundManagement.PartnerUI/ # External Grantee / Recipient Portal (React 19 + Vite)
|
|
├── Architecture.md # System Architecture, RBAC & Maker-Checker Spec
|
|
├── Processes.md # Operational Grant Lifecycle & Process Flows
|
|
└── docker-compose.yml # Container orchestration
|
|
```
|
|
|
|
## 🚀 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.
|