# Punkit Creative — Expense Command Center
## Finance Department | Developer Handover & Implementation Guide

This document outlines the architecture, data flow, and deployment steps for **Finance Automation 4: Expense Claim Automation**.

---

## 1. System Architecture Overview

*   **Frontend (Expense Command Center V3):** A highly efficient, side-by-side verification dashboard (`expense_claim_dashboard.html`) utilizing the global Punkit Orange/Teal brand theme.
    *   **V3 Enterprise Features:** Includes Payment Method routing (Out-of-Pocket vs Corporate Card), Lost Receipt Declaration handling, AI Policy Enforcer banners, Unregistered Vendor warnings, Duplicate Receipt detection, and an Employee Profile slide-over.
*   **Backend (n8n Workflow V3):** The workflow (`expense_claim_workflow.json`) handles the two-way WhatsApp communication, Xero syncing, and Policy Enforcement.
    1. **Inbound Trigger:** A Webhook receives POST requests from the WhatsApp Cloud API whenever an employee sends a photo.
    2. **Xero Data Fetch:** n8n pulls the full Approved Supplier List and Chart of Accounts from Xero.
    3. **AI Vision & Policy Audit:** `OpenAI` (`gpt-4o`) extracts the Merchant, Amount, Date, and Receipt Number. It cross-references the merchant against the Xero Supplier List, categorizes the expense, determines the Payment Method, and audits the line items against the Company Expense Policy.
    4. **Dashboard Sink:** n8n pushes this structured JSON to the dashboard's database.
    5. **WhatsApp Auto-Reply:** n8n sends a quick WhatsApp back to the employee confirming receipt of the expense.
    6. **Dashboard Action:** When the manager clicks "Approve" or "Reject", the dashboard hits an n8n webhook.
    7. **Sync or Reject:**
        *   If Approved (Out of Pocket): n8n creates a Reimbursable Expense Claim in Xero.
        *   If Approved (Corporate Card): n8n creates a 'Spend Money' transaction on the Xero Bank Feed.
        *   If Rejected: n8n uses the `WhatsApp` node to send the manager's typed rejection reason straight back to the employee.
    8. **Receipt Chaser (CRON):** Every Friday at 3PM, n8n scans the Xero Bank Feed for Corporate Card swipes missing attachments, and automatically sends a WhatsApp to the employee demanding the slip.

---

## 2. Webhook API Schema

### A. Dashboard Action Webhook (Dashboard → n8n)
When the Manager clicks a button, the frontend must POST this payload to n8n to trigger the rest of the workflow.

**Approved Payload:**
```json
POST https://n8n.punkit.co.za/webhook/expense-action
Content-Type: application/json

{
  "action": "approve",
  "employeePhone": "+27821234567",
  "employeeXeroId": "xero-contact-id-123",
  "merchant": "Starbucks CPT",
  "amount": 145.00,
  "categoryCode": "429",
  "date": "2026-06-22"
}
```

**Rejected Payload:**
```json
POST https://n8n.punkit.co.za/webhook/expense-action
Content-Type: application/json

{
  "action": "reject",
  "employeePhone": "+27821234567",
  "merchant": "Starbucks CPT",
  "rejectReason": "The VAT number is cut off at the bottom. Please retake the photo."
}
```

---

## 3. Implementation Steps

### Phase 1: WhatsApp API Setup
1. You must register a dedicated phone number with the **WhatsApp Cloud API** (via Meta for Developers).
2. Configure the WhatsApp Webhook to point directly to the n8n `Webhook (WhatsApp Incoming)` node URL.
3. Update the `WhatsApp` nodes in the n8n workflow with your `PhoneNumberId` and Meta Access Token.

### Phase 2: n8n & Xero
1. Import `expense_claim_workflow.json` into n8n.
2. Authenticate the Xero node using your OAuth2 credentials.
3. Ensure the OpenAI node has an active API key with access to `gpt-4o` for vision capabilities.

### Phase 3: Dashboard Frontend
1. Host `expense_claim_dashboard.html`.
2. Connect it to your database. The dashboard currently uses a static `INBOX` array in the javascript. This needs to be replaced with a live `fetch()` call to your database where the incoming WhatsApp payloads are stored.