From b48c66375648c20a6516948bfddc21a0b1bd3d84 Mon Sep 17 00:00:00 2001
From: Hermes Agent <hermes@litecharms.co.za>
Date: Thu, 20 Aug 2026 17:04:32 +0200
Subject: [PATCH] Added readme

---
 README.md | 120 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 120 insertions(+)
 create mode 100644 README.md

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..7490ecd
--- /dev/null
+++ b/README.md
@@ -0,0 +1,120 @@
+# 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.
+
+[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 8 / 9 C# Web API
+* **Database**: PostgreSQL
+* **ORM**: Entity Framework Core (Fluent API Configuration)
+* **Architecture**: Clean Architecture / Domain-Driven Design (DDD) with CQRS (`MediatR`)
+* **Utilities**: `Humanizer` (Automated entity-to-table pluralization)
+
+---
+
+## 📁 Solution Structure
+
+```text
+src/
+ ├── PostFundManagement.Domain/         # Core Domain Entities, Enums & Interfaces
+ ├── PostFundManagement.Infrastructure/ # EF Core Configurations, DbContext, Migrations
+ ├── PostFundManagement.Application/    # CQRS Handlers, DTOs, Business Rules & Logic
+ └── PostFundManagement.Api/            # REST Controllers, Middleware, Auth & Swagger
+```
+
+## 🚀 Getting Started
+
+### Prerequisites
+
+.NET 8.0 SDK or higher
+PostgreSQL 14+
+dotnet-ef CLI Tool (dotnet tool install --global dotnet-ef)
+
+## Setup & Execution
+
+## Clone Repository
+
+1. Clone Repository:
+
+```bash
+git clone [https://github.com/your-org/PostFundManagement.git](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. Apply Database Migrations:
+
+```bash
+dotnet ef database update --project src/PostFundManagement.Infrastructure
+```
+
+4. Launch Application:
+
+```bash
+dotnet run --project src/PostFundManagement.Api
+```
+
+## 📄 License
+
+Internal Proprietary Software — All rights reserved.