Module — Grant

Financial master data and budget management. It owns donor-funded Projects (with extensions, places, programmes and donors), the Master Budget and its monthly detail lines, project Budget Lines (procurement and personnel), staff cost Allocations across budget lines and donors, and the donor / global Exchange Rates that the whole system uses for currency conversion.

Source: NKO.Main/NKO.Main/Controllers/{MasterBudget,BudgetLines,Allocations,ExchangeRate,Project}Controller.cs, NKO.Main/NKO.Main/BAL/{BMasterBudget,BBudgetLinesCategory,BExchangeRate,BDonor,BProject,AllocationHandler,BudgetLinesHandler,ProcBudgetLineHandler}.cs.

Purpose & scope

• In scope: Projects and their satellites, the Master Budget → monthly detail, Budget Lines and their payment schedules, salary Allocations, donor and global Exchange Rates, and the aggregation that rolls procurement and payroll spend back up against a budget.
• Out of scope: raising purchase documents (Procurement) and running payroll (Payroll) — Grant provides the budget lines and rates those modules charge against.
• Database: NKO_DB (core), context NKO_DBEntities1.

Key features

• Projects — CRUD with places / donors / programmes / attachments (S3); manager roles (Program / Finance / Logistic / HR / Compliance) and segregation-of-duty fields (Sod1–4, FinanceSod1); currency and exchange rate; contract number; warehouse activation; extensions (cost / no-cost, amount, dates, code); monthly amounts; a status (ProjectStatus); validity = end date (or an active extension) ≥ today; focal-point notifications on create / update; a per-project allocations screen; export by month / year.
• Master Budget — a header (start / end / notes) plus detail lines (category, place, quantity, amount, dates) auto-split into monthly rows (pro-rata by day / 30); month edit (budget vs. real amount); Excel import / export of detail lines; the "AllocationBase", "FullMasterBudget" and "AllocationCosts" analytical views; GetDifferenceAmount / GetConsumedAmount (budget − real).
• Budget Lines — per project; Type = Procurement / Personnel / Both; procurement lines carry Code / Title / Qty / Duration / LOE / Amount / OtherDeductions / UnitId / CategoryId / MasterBudgetDetailId; personnel lines carry a PositionId + assigned users and generate monthly BudgetLinePayment rows; "ProcBudgetLines" and "Employees" views; a budget report aggregating PR / PO / PTO spend; import / export; a BudgetLinesCategory lookup.
• Allocations — create / edit / delete AppUserAllocation; a per-employee Allocate screen (LOE % per budget line, donor-based FX conversion to USD / EUR); a Salary roll-up; budget-line search per project.
• Exchange Rates — the single global ExchangeRates row (EURRate / SYPRate / TRYRate, with an external fetch from data.fixer.io, base TRY — written but never called, R7-17) and per-donor DonorExchangeRate (year, month, USD, EUR) CRUD under a donor.

Screens

Route = /{Controller}/{Action}; primary screens only.

ProjectController — /Project/*

Feature	Route	View	Permission key
Projects list	/Project/Index	Project/Index.cshtml	ProjectIndex
Project detail	/Project/Details/{id}	Details.cshtml	ProjectDetails
Create / edit	/Project/Create, /Project/Edit/{id}	Create.cshtml, Edit.cshtml	ProjectCreate, ProjectEdit
Extensions	/Project/AddExtension/{id}, /Project/EditExtension/{id}	_AddExtension.cshtml	ProjectAddExtension, ProjectEditExtension
Monthly amounts	/Project/EditMonth/{id}	_EditMonth.cshtml	ProjectEditMonth
Per-project allocations	/Project/Allocations/{id}	Allocations.cshtml	ProjectAllocations
Export	/Project/Export	Export.cshtml	ProjectExport

MasterBudgetController — /MasterBudget/*

Feature	Route	View	Permission key
Master budgets list	/MasterBudget/Index	MasterBudget/Index.cshtml	MasterBudgetIndex
Detail (lines)	/MasterBudget/Details/{id}	Details.cshtml	MasterBudgetDetails
Monthly split	/MasterBudget/MonthDetails/{id}	MonthDetails.cshtml	MasterBudgetDetails
Create budget / detail line / month rows	/MasterBudget/Create, /MasterBudget/CreateMBDetails/{id}, /MasterBudget/CreateMBMonthDetails/{id}	Create.cshtml, _Create*.cshtml	MasterBudgetCreate
Analytical views	/MasterBudget/AllocationBase, /MasterBudget/FullMasterBudget, /MasterBudget/AllocationCosts/{id}	*.cshtml	MasterBudgetCreate / MasterBudgetIndex
Import / export detail lines	/MasterBudget/ImportMBDetails/{id}, /MasterBudget/ExportMBDetails/{id}	_ImportMBDetails.cshtml	MasterBudgetCreate / MasterBudgetDetails

BudgetLinesController — /BudgetLines/*

Feature	Route	View	Permission key
Budget-lines grid	/BudgetLines/Index	BudgetLines/Index.cshtml	BudgetLinesIndex
Procurement budget-line consumption	/BudgetLines/ProcBudgetLines/{projectGuid}	ProcBudgetLines.cshtml	BudgetLinesIndex
Personnel allocation coverage	/BudgetLines/Employees	Employees.cshtml	BudgetLinesIndex
Detail	/BudgetLines/Details/{id}	Details.cshtml	BudgetLinesDetails
Create / edit / delete	/BudgetLines/Create/{id}, /BudgetLines/Edit/{id}, /BudgetLines/Delete/{id}	Create/Edit/Delete.cshtml	BudgetLinesCreate, BudgetLinesDelete
Import / export	/BudgetLines/Import/{projectId}, /BudgetLines/Export	_Import.cshtml	BudgetLinesCreate, BudgetLinesIndex

AllocationsController — /Allocations/* · ExchangeRateController — /ExchangeRate/*

Feature	Route	View	Permission key
Allocations list / detail / create / edit / delete	/Allocations/Index, /Allocations/Details/{id}, /Allocations/Create, /Allocations/Edit/{id}, /Allocations/Delete/{id}	Allocations/*.cshtml	AllocationsIndex
Per-employee allocate (LOE split)	/Allocations/Allocate/{id}	Allocate.cshtml	AllocationsIndex
Salary roll-up	/Allocations/Salary	Salary.cshtml	AllocationsIndex
Donor list	/ExchangeRate/Index	ExchangeRate/Index.cshtml	ExchangeRateIndex
Per-month USD/EUR rate table for a donor	/ExchangeRate/ExchangeRates/{donorGuid}	ExchangeRates.cshtml	ExchangeRateIndex
Create / edit / delete a donor rate	/ExchangeRate/CreateExchangeRate/{donorId}, /ExchangeRate/EditExchangeRate/{id}	_*ExchangeRate.cshtml	ExchangeRateIndex

Business logic

Class	File	Responsibility & notable logic
BProject	NKO.Main/NKO.Main/BAL/BProject.cs (~725 ln)	Create — parses ReferenceNumber from the segment of ProjectCode after the last -; builds ProjectPlace / ProjectDonors / ProjectProgram; uploads attachments to S3; notifies GetProjectsFocalPoints + e-mail. Edit — removes & re-adds the satellites, copies the manager & SOD fields. AddExtension / EditExtension / EditMonthDetails. Validity queries: GetValidProjects (end ≥ now OR an extension covering today), GetApprovedProjects (StatusId == Approved & within dates), GetProgram/Finance/LogisticManagerProjects. Authorisation: GetAuthorizedProjects(userId, permissionType, areaId) over AppUserProjectPermissions. Remove soft-deletes the project and cascades to its BudgetLines.
BMasterBudget	NKO.Main/NKO.Main/BAL/BMasterBudget.cs (~470 ln)	CreateDetails → CalculatePayments(start, end, amount) → one MasterBudgetDetailsMonths per month (full calendar month → amount; partial → amount / 30 × (endDay − startDay + 1)). EditDetails regenerates the month rows (resets RealAmount to 0). GetDifferenceAmount(ids) = Σ month.BudgetAmount − Σ month.RealAmount; GetConsumedAmount = Σ month.RealAmount.
AllocationHandler	NKO.Main/NKO.Main/BAL/AllocationHandler.cs (~400 ln; contract IAllocationHandler)	Add / Calculate(model, year, month, userId) — reject if Σ LOE > 100; wipe the user's month allocations; get their PayrollInfo; per line ratio = payrollInfo.BasicSalary × (LOE / 100); look up DonorExchangeRate (donor + month + year) → SalaryAmountUSD = ratio × ExchangeRateUsd, …EURO = ratio × ExchangeRateEuro; write AppUserAllocation. A missing rate → AllocationCreateStatus.ExchangeRateRequired. GetSalarys(month, year) — per user aggregate budgetline.Amount × SalaryRatio (salary) and × BenefitRatio (benefit).
ProcBudgetLineHandler	NKO.Main/NKO.Main/BAL/ProcBudgetLineHandler.cs (~800 ln; contract IProcBudgetLineHandler — wired to BudgetLinesController)	The procurement ↔ finance bridge. Add — creates a BudgetLine; for non-procurement types attaches BudgetLinesUser and calls CreatePayments. CreatePayments(start, end, amount, budgetLineId) — monthly split (partial month amount / 30 × (days + 1)) → BudgetLinePayment. BudgetFlush(mbDetailId) — recomputes MasterBudgetDetailsMonths.RealAmount = Σ BudgetLinePayment.Amount (rolls line spend into the master budget). BudgetReport(guid) — per line: Accepted PR (Materials.EstTotalPrice), Accepted PO (PurchaseOrderMat.Total), Accepted / Paid Payment Orders. Reallocate(month, year) — regenerates AppUserAllocation for every payroll user (LOE-capped so cumulative ≤ 100; ratio = salary × currentPercent; DonorExchangeRate conversion; leftover < 100 % goes onto hard-coded BudgetLineId 12). Called by BPayroll.Generate.
BudgetLinesHandler	NKO.Main/NKO.Main/BAL/BudgetLinesHandler.cs (~730 ln; contract IBudgetLinesHandler)	The older personnel-oriented variant, still injected into AllocationHandler. Add / Update; CreatePayments (same monthly pro-rata); CalcBalance(id) — ConsumedAmount = Σ AppUserAllocations.SalaryAmountTL; day-accurate GetDetails / GetPassedMonthsCount with a leap-aware monthDay[13] table.
BExchangeRate	NKO.Main/NKO.Main/BAL/BExchangeRate.cs	GetExchangeRate(date) — HTTP GET data.fixer.io/api/{date}?base=TRY&symbols=USD,EUR. Get() — the single ExchangeRates row where IsEnable.
BDonor, BBudgetLinesCategory	NKO.Main/NKO.Main/BAL/	Donor + DonorExchangeRate CRUD (GetExcahngeRates, Add, EditExchangeRate); BudgetLinesCategory CRUD (description-only edit).

Known code issues (advisory — see Recommendations)

BExchangeRate.Update reassigns each field to itself, so a rate edit currently saves nothing (R7-1). Separately, AllocationHandler.Add / Calculate and ProcBudgetLineHandler copy ExchangeRateUsd into the ExchangeRateEuro column (R7-2). The EUR amounts are correct — SalaryAmountEURO is computed with the real EUR rate — so only the stored audit column misstates the rate that was applied.

Data

• Budget: MasterBudget, MasterBudgetDetails, MasterBudgetDetailsMonths; BudgetLine (NotMapped Balance = Amount − Σ PurchaseOrderMat.Total, IsAvailable = Balance ≥ 0), BudgetLineBranch, BudgetLinePayment, BudgetLinesCategory, BudgetLinesUser.
• Rates & donors: ExchangeRates, DonorExchangeRate, Donor, MainDonor, DonorPartners, ProjectDonors, PartnersContribution, PartnersContributionMain.
• Projects: Project, ProjectExtensions, ProjectMonths, ProjectPlace, ProjectProgram, ProjectFilterSettings, CommitteeUser (entity here, but written by RFQ — see Procurement).

Full column detail: Finance database.

Permissions

Distinct keys: MasterBudgetIndex, MasterBudgetCreate, MasterBudgetDetails, BudgetLinesIndex, BudgetLinesDetails, BudgetLinesCreate, BudgetLinesDelete, AllocationsIndex, ExchangeRateIndex, ProjectIndex, ProjectDetails, ProjectCreate, ProjectEdit, ProjectAllocations, ProjectAddExtension, ProjectEditExtension, ProjectEditMonth, ProjectExport, ProjectDeleteActivity. Cross-module keys reused: General, HumanResourceDeleteAttachment, PurchaseRequestAddComment. Per-project access is scoped through AppUserProjectPermission (see Permissions).

Screenshots

Projects — /Project:

Master Budget — /MasterBudget:

Actual Budget / budget lines — /BudgetLines:

Salary allocations — /Allocations:

Donor exchange rates — /ExchangeRate/ExchangeRates/{donor} (reached from /Admin/Donors → "Exchange Rates"):

Related

• Procurement module — every PR / PO line is charged to a Grant budget line (availability is shown, not enforced).
• Payroll module — ProcBudgetLineHandler.Reallocate and DonorExchangeRate drive salary allocation.
• Grant API · Finance database.