# 💰 ChurchCRM Expense Management Module

**Version 1.0** | Complete Expense Tracking & Financial Management for ChurchCRM

---

## 🎯 Overview

The **Expense Management Module** is a complete financial tracking solution that extends ChurchCRM to include expense recording, approval workflows, budget tracking, and detailed financial reporting. Track everything your church spends and calculate true net account balance (Income - Expenses).

---

## ✨ Features

### 📊 **Core Features**
- ✅ **Expense Recording** - Enter expenses by category with full details
- ✅ **Payment Methods** - Track check, cash, credit card, bank transfers
- ✅ **Approval Workflow** - Pending → Approved → Paid status flow
- ✅ **Expense Categories** - Pre-configured categories (Utilities, Salaries, Supplies, etc.)
- ✅ **Budget Tracking** - Set and track budgets per category
- ✅ **Financial Reports** - Income vs Expenses, Account Balance
- ✅ **Approval Audit Trail** - Complete history of all approvals/rejections

### 👥 **Role-Based Access**
- **Finance Users** - Can enter expenses, view reports, add payments
- **Admin Users** - Full access plus approval/rejection rights, manage categories
- **Other Users** - No access (automatic)

### 📈 **Reporting & Analytics**
- Expenses by category breakdown
- Monthly summaries
- Budget vs actual spending
- Pending approval dashboard
- Financial summary (Income - Expenses = Balance)

---

## 🚀 Getting Started

### **Step 1: Access the Expense Module**

**Via Finance Menu:**
- Go to **Finance** → **Expenses**
- Three options appear:
  - **Add Expense** - Record a new expense
  - **View All Expenses** - See expense list
  - **Financial Summary** - Income vs Expenses report

### **Step 2: Add Your First Expense**

1. Click **Finance** → **Expenses** → **Add Expense**
2. Fill in the form:
   - **Date** - When the expense occurred
   - **Amount** - How much (e.g., $150.00)
   - **Category** - What type (Utilities, Salaries, etc.)
   - **Payment Method** - How you paid (Check, Cash, Credit Card)
   - **Vendor** - Who you paid (e.g., "Electric Company")
   - **Reference** - Invoice # or Check #
   - **Description** - Details about the expense
   - **Notes** - Additional information

3. Click **"Save Expense"**
   - Status becomes **"Pending"** for approval

### **Step 3: Approve or Reject (Admin Only)**

**In Expense List:**
- Admins see **Approve** and **Reject** buttons for Pending expenses
- Click button to change status
- Add notes if needed

**Status Flow:**
```
Pending (submitted) 
   ↓ [Admin Action]
Approved OR Rejected
   ↓ [If Approved]
Paid (marked complete)
```

---

## 📋 Expense Categories

Pre-configured categories:

| Category | Purpose |
|----------|---------|
| **Utilities** | Electric, Gas, Water, Internet |
| **Salaries** | Staff and Payroll |
| **Supplies** | Office and Building Supplies |
| **Maintenance** | Building Maintenance and Repairs |
| **Programs** | Youth, Adult, Children Programs |
| **Outreach** | Missions and Community Outreach |
| **Insurance** | Building and Liability Insurance |
| **Transportation** | Fuel and Vehicle Maintenance |
| **Professional Services** | Accounting, Legal, Consulting |
| **Equipment** | Computers, Equipment, Technology |
| **Other** | Miscellaneous Expenses |

### **Add Custom Categories (Admin)**

1. Go to **Finance** → **Admin** → **Expense Categories**
2. Fill the form on the right:
   - **Category Name** (e.g., "Events")
   - **Description** (optional)
   - Check "Active" to enable
3. Click **"Add Category"**

---

## 💼 Payment Methods

Track how expenses were paid:
- **Check** - Physical check with number
- **Cash** - Cash payment
- **Credit Card** - Credit/debit card transaction
- **Bank Transfer** - ACH or wire transfer
- **Other** - Other methods

---

## 📊 Financial Reports

### **Financial Summary Report**

Shows the complete financial picture:

1. Go to **Finance** → **Expenses** → **Financial Summary**

**Displays:**
- **Total Income** - From all deposits and offerings
- **Total Expenses** - Sum of all approved expenses
- **Net Balance** - Income minus Expenses
- **Expenses by Category** - Breakdown chart
- **Budget vs Actual** - How spending compares to budget

### **Filter by Date Range**

- Set Start and End dates
- Click **"Filter"** to update report

**Example Report:**
```
Total Income:        $15,000.00
Total Expenses:      $4,250.00
─────────────────────────────────
NET BALANCE:         $10,750.00

By Category:
├─ Salaries:        $2,500.00 (58.8%)
├─ Utilities:        $850.00 (20%)
├─ Supplies:         $600.00 (14%)
└─ Other:            $300.00 (7%)
```

---

## 🎯 Workflow Example: Sunday Utilities Bill

**Scenario:** Electric bill arrived for $350 for utilities

1. **Finance Person Enters Expense:**
   - Date: 6/5/2026
   - Amount: $350.00
   - Category: Utilities
   - Vendor: "Electric Company"
   - Reference: "Invoice #INV-2026-0542"
   - Description: "Monthly electric bill"
   - Click **Save** → Status = **Pending**

2. **Admin Reviews:**
   - Goes to **Expense List**
   - Sees **Pending** expense
   - Clicks **Approve** button
   - Status changes to **Approved** ✓

3. **Finance Marks as Paid:**
   - Once check is written/bill paid
   - Clicks **Mark Paid** button
   - Status changes to **Paid** ✓

4. **Reports Updated:**
   - Financial Summary automatically includes expense
   - Balance calculation updated
   - Category totals updated

---

## 🔐 Permissions

### **Finance Users Can:**
- ✅ Add new expenses
- ✅ View all expenses
- ✅ View financial reports
- ✅ Edit their own pending expenses
- ❌ Approve/reject expenses
- ❌ Delete expenses
- ❌ Manage categories

### **Admin Users Can:**
- ✅ All Finance permissions PLUS:
- ✅ Approve/reject expenses
- ✅ Mark expenses as paid
- ✅ Delete expenses
- ✅ Add/edit/delete categories
- ✅ Manage budgets

### **Other Users:**
- ❌ No access to expense module

---

## 💡 Tips & Best Practices

### **1. Check Numbers**
If paying by check, note the check number in the **Reference** field:
- Example: "Check #1234"
- Helps reconcile with bank statements

### **2. Vendor Names**
Use consistent vendor names for better reporting:
- ✅ "Electric Company" (consistent)
- ❌ "Elec Co", "Electric", "Light Co" (inconsistent)

### **3. Detailed Descriptions**
Add context in description field:
- ✅ "Monthly electric bill for sanctuary building"
- ❌ "Bill"

### **4. Reference Numbers**
Always capture invoice/reference numbers:
- Invoice #
- Purchase Order #
- Receipt #
- Check #

### **5. Regular Reconciliation**
Weekly/Monthly:
- Review pending expenses
- Approve legitimate expenses
- Compare to bank statements

### **6. Budget Monitoring**
Set realistic budgets:
- Compare current spending to budget
- Adjust categories if needed
- Flag over-budget items

---

## 🔍 Common Tasks

### **View All Pending Expenses**

1. Finance → Expenses → View All Expenses
2. Look for **Pending** badge
3. Count shown in dashboard

### **Check Budget Status**

1. Finance → Expenses → Financial Summary
2. Compare "Actual" vs "Budgeted" columns
3. Identify over-budget categories

### **Export Expense Report**

(Future Feature - Coming Soon)

### **Delete an Expense**

1. Finance → Expenses → View All Expenses
2. Find the expense
3. Click **Trash** icon
4. Confirm deletion

---

## 🗄️ Database Schema

### **Main Tables**

**expense_exp** - Individual expense records
- exp_ID - Unique identifier
- exp_Date - When expense occurred
- exp_Amount - Dollar amount
- exp_Category - Category ID
- exp_Fund - Associated fund (optional)
- exp_Vendor - Who was paid
- exp_Description - Details
- exp_Status - Pending/Approved/Rejected/Paid
- exp_PaymentMethod - How paid
- exp_EnteredBy - User who entered
- exp_ApprovedBy - Admin who approved

**expense_category_cat** - Expense categories
- cat_ID - Category ID
- cat_Name - Category name
- cat_Description - Description
- cat_Active - Is this active?

**expense_budget_bud** - Budget allocations
- bud_ID - Budget record ID
- bud_Year - Year
- bud_Category - Category ID
- bud_Fund - Fund ID
- bud_Amount - Budgeted amount

**expense_approval_log_eal** - Audit trail
- eal_ID - Log entry ID
- eal_ExpenseID - Expense ID
- eal_Action - Submitted/Approved/Rejected/Paid
- eal_UserId - Who performed action
- eal_Timestamp - When it happened

---

## 🛠️ API Endpoints

For developers, REST API endpoints:

### **Expenses**
```
GET    /api/expenses                          - List all expenses
POST   /api/expenses                          - Create expense
GET    /api/expenses/{id}                     - Get expense detail
PUT    /api/expenses/{id}                     - Update expense
DELETE /api/expenses/{id}                     - Delete expense
POST   /api/expenses/{id}/approve             - Approve expense
POST   /api/expenses/{id}/reject              - Reject expense
POST   /api/expenses/{id}/pay                 - Mark as paid
```

### **Categories**
```
GET    /api/expense-categories                - List categories
POST   /api/expense-categories                - Create category
DELETE /api/expense-categories/{id}           - Delete category
```

### **Reports**
```
GET    /api/expenses/dashboard/summary        - Get dashboard summary
```

---

## ❓ FAQ

**Q: Can I edit an expense after approval?**
A: Not yet. Delete and re-enter (coming in next version).

**Q: Can I set budgets?**
A: Yes, in Financial Summary report (future: admin interface).

**Q: What if I enter an expense by mistake?**
A: Delete it from Expense List (admin or Finance can delete Pending).

**Q: Can I see who approved what?**
A: Yes, approval audit trail is logged (view in expense details).

**Q: Does this track where money comes from?**
A: This tracks expenses. Deposits/income tracked in Finance → Deposits.

**Q: Can I print expense report?**
A: Future feature - currently view on screen or screenshot.

---

## 📞 Support

**Issues or questions?**
- Check this guide first
- All features documented above
- Module fully integrated with ChurchCRM

---

## 📝 Version History

**v1.0 - Initial Release**
- ✅ Expense entry and tracking
- ✅ Approval workflow
- ✅ Category management
- ✅ Financial reporting
- ✅ Audit trail logging
- ✅ Role-based access control

---

## 🎉 What You Can Now Do

**BEFORE (Without Expense Module):**
- ❌ Couldn't track expenses in ChurchCRM
- ❌ Couldn't calculate true account balance
- ❌ Expenses recorded separately in spreadsheets
- ❌ No approval workflow
- ❌ Unclear spending patterns

**NOW (With Expense Module):**
- ✅ Track all expenses in ChurchCRM
- ✅ Calculate real account balance (Income - Expenses)
- ✅ Approve/reject before paying
- ✅ See spending patterns by category
- ✅ Monitor budgets
- ✅ Complete audit trail
- ✅ Professional financial reporting

---

## 🚀 Next Steps

1. **Set up categories** - Admin → Expense Categories (customize for your church)
2. **Set budgets** - Finance → Financial Summary (budget per category)
3. **Start entering expenses** - Finance → Expenses → Add Expense
4. **Review weekly** - Check pending expenses and approve
5. **Generate reports** - Financial Summary shows complete picture

---

**Ready to track your church finances completely? Start adding expenses now!** 💪

