Budgeting & Finance
Relevant source files
The following files were used as context for generating this wiki page:
The Budgeting & Finance system provides a comprehensive framework for managing IT-related financial records, including annual and monthly budget allocations, actual expense tracking, and forecast revisions. It is designed to offer a multi-tenant environment where financial data is strictly scoped by company_id.
The system distinguishes between Source Data Modules (CRUD-based entry points for budgets and expenses) and the Budget Report, which acts as a read-only analytics engine to aggregate data for financial reviews.
Sources: wiki/Modules.md:68-73, modules/budget_report/AGENT_NOTES.md:1-5
System Architecture & Data Flow
The finance system operates on a tiered structure. Financial data is categorized using lookup tables before being allocated to annual budgets, which are then subdivided into monthly targets. Actual expenditures are tracked against these targets to provide variance analysis.
Financial Entity Relationships
The following diagram illustrates how financial records relate to organizational structures like Cost Centers and GL Accounts.
The system maintains strict referential integrity; for instance, deleting an annual budget will cascade delete its associated monthly breakdowns.
Sources: modules/annual_budgets/AGENT_NOTES.md:7-14, modules/monthly_budgets/AGENT_NOTES.md:7-9, modules/expenses/AGENT_NOTES.md:7-10
Core Finance Modules
1. Annual & Monthly Budgets
Annual budgets manage financial allocations per Cost Center and GL Account for a specific fiscal year. Only one budget record is permitted per combination of company, cost center, GL account, and year. Monthly budgets provide finer control by breaking these annual sums into 12 periods.
Sources: modules/annual_budgets/AGENT_NOTES.md:1-25, modules/monthly_budgets/AGENT_NOTES.md:1-15
2. Expenses
The Expenses module tracks actual financial expenditures. Each expense is tied to a date, which the system uses to determine the impact on specific budget months and years. Amounts are stored with 2-decimal precision.
Sources: modules/expenses/AGENT_NOTES.md:1-15
3. Forecast Revisions & Approvals
Forecast revisions allow for dynamic adjustments to the budget as the fiscal year progresses. These revisions can be subject to an approval workflow, moving through stages (e.g., Pending, Approved, Locked) to ensure financial oversight.
Sources: modules/forecast_revisions/AGENT_NOTES.md:1-15, modules/approvals/AGENT_NOTES.md:1-15
Budget Report (Analytics)
The Budget Report is a non-CRUD module that serves as the primary interface for financial review. It aggregates data from the annual_budgets, monthly_budgets, and expenses tables to provide MoM (Month-over-Month) and YoY (Year-over-Year) comparisons.
Comparison Logic
The report interface allows users to filter by Year, Month, Cost Center, and GL Account. It displays:
- Current Actuals: Sum of expenses for the selected period.
- Previous Month: Aggregated totals for the preceding month.
- Previous Year: Aggregated totals for the same month in the prior year.
Sources: modules/budget_report/AGENT_NOTES.md:1-25, wiki/Modules.md:75-85
Technical Implementation Details
API & Data Import
Most budgeting modules support bulk data entry via a specialized JSON endpoint (import_excel_rows). This endpoint is used by the frontend table-tools.js to process Excel/CSV uploads.
| Endpoint | Method | Purpose |
|---|---|---|
modules/annual_budgets/index.php | POST | Bulk import annual budget records |
modules/expenses/index.php | POST | Bulk import expense records |
modules/forecast_revisions/index.php | POST | Bulk import forecast adjustments |
Sources: scripts/api.php:121-140, modules/annual_budgets/AGENT_NOTES.md:21-23
Multi-Tenancy & Security
Every query in the finance system is strictly scoped by company_id retrieved from the authenticated session. Direct modification of the company context via API payloads is prohibited.
// Example of tenant-safe aggregation in budget_report
$stmt = $conn->prepare("SELECT SUM(amount) as total FROM expenses WHERE company_id = ? AND year = ? AND month = ?");
$stmt->bind_param("iii", $companyId, $year, $month);
$stmt->execute();
Sources: modules/budget_report/AGENT_NOTES.md:30-35, scripts/api.php:112-116
Summary
The Budgeting & Finance system provides the necessary tools for IT financial governance. By separating data entry (Budgets, Expenses, Forecasts) from analytical reporting, the system ensures that management can perform accurate variance analysis and period-based comparisons while maintaining strict multi-tenant data isolation.
Sources: modules/budget_report/AGENT_NOTES.md:40-42, wiki/Modules.md:175-180