{ "feature": "expense-approval", "version": "1.0.0", "description": "Submit and approve employee expense reports with receipt validation", "category": "data", "tags": [ "expense", "approval", "workflow", "finance", "reimbursement" ], "actors": [ { "id": "employee", "name": "Employee", "type": "human", "description": "Submits expense reports for reimbursement", "role": "any" }, { "id": "manager", "name": "Direct Manager", "type": "human", "description": "First-level approval for all expenses", "role": "management" }, { "id": "finance_manager", "name": "Finance Manager", "type": "human", "description": "Second-level approval required for expenses over threshold", "role": "finance" }, { "id": "payment_system", "name": "Payment System", "type": "system", "description": "Processes approved reimbursements via payroll or direct deposit" }, { "id": "audit_system", "name": "Audit Logger", "type": "system", "description": "Records all state transitions for compliance" } ], "fields": [ { "name": "title", "type": "text", "required": true, "label": "Expense Title", "placeholder": "Q1 Client Dinner", "validation": [ { "type": "required", "message": "Title is required" }, { "type": "maxLength", "value": 200, "message": "Title is too long" } ] }, { "name": "amount", "type": "number", "required": true, "label": "Amount", "placeholder": "0.00", "validation": [ { "type": "required", "message": "Amount is required" }, { "type": "min", "value": 0.01, "message": "Amount must be greater than zero" }, { "type": "max", "value": 50000, "message": "Expenses over $50,000 require a separate purchase order" } ] }, { "name": "currency", "type": "select", "required": true, "label": "Currency", "default": "USD", "options": [ { "value": "USD", "label": "US Dollar" }, { "value": "EUR", "label": "Euro" }, { "value": "GBP", "label": "British Pound" } ] }, { "name": "category", "type": "select", "required": true, "label": "Expense Category", "options": [ { "value": "travel", "label": "Travel" }, { "value": "meals", "label": "Meals & Entertainment" }, { "value": "supplies", "label": "Office Supplies" }, { "value": "software", "label": "Software & Subscriptions" }, { "value": "equipment", "label": "Equipment" }, { "value": "other", "label": "Other" } ] }, { "name": "date_incurred", "type": "date", "required": true, "label": "Date of Expense", "validation": [ { "type": "required", "message": "Date is required" }, { "type": "custom", "value": "date <= today AND date >= today - 90 days", "message": "Expense must be within the last 90 days" } ] }, { "name": "description", "type": "rich_text", "required": true, "label": "Description & Business Justification", "placeholder": "Describe the expense and why it was necessary", "validation": [ { "type": "required", "message": "Description is required" }, { "type": "minLength", "value": 10, "message": "Please provide a more detailed description" } ] }, { "name": "receipt", "type": "file", "required": false, "label": "Receipt", "validation": [ { "type": "custom", "value": "file.size <= 10MB AND file.type IN [pdf, png, jpg, jpeg]", "message": "Receipt must be a PDF or image under 10MB" } ] }, { "name": "status", "type": "select", "required": true, "label": "Status", "default": "draft", "immutable": false, "options": [ { "value": "draft", "label": "Draft" }, { "value": "submitted", "label": "Submitted" }, { "value": "manager_approved", "label": "Manager Approved" }, { "value": "pending_finance", "label": "Pending Finance Review" }, { "value": "approved", "label": "Approved" }, { "value": "rejected", "label": "Rejected" }, { "value": "paid", "label": "Paid" } ] }, { "name": "rejection_reason", "type": "text", "required": false, "label": "Rejection Reason" }, { "name": "submitted_by", "type": "hidden", "required": true, "sensitive": false, "immutable": true, "label": "Submitted By" }, { "name": "approved_by", "type": "hidden", "required": false, "label": "Approved By" } ], "states": { "field": "status", "values": { "draft": { "label": "Draft", "initial": true, "description": "Employee is preparing the expense report" }, "submitted": { "label": "Submitted", "description": "Awaiting manager review" }, "manager_approved": { "label": "Manager Approved", "description": "Manager approved; may need finance review for large amounts" }, "pending_finance": { "label": "Pending Finance Review", "description": "Requires finance manager sign-off (amount over threshold)" }, "approved": { "label": "Approved", "description": "Fully approved, queued for payment" }, "rejected": { "label": "Rejected", "terminal": true, "description": "Rejected by manager or finance — employee can revise and resubmit" }, "paid": { "label": "Paid", "terminal": true, "description": "Reimbursement processed" } }, "transitions": { "submit": { "from": "draft", "to": "submitted", "actor": "employee", "description": "Employee submits expense for approval" }, "manager_approve": { "from": "submitted", "to": "manager_approved", "actor": "manager", "description": "Direct manager approves the expense" }, "escalate_to_finance": { "from": "manager_approved", "to": "pending_finance", "actor": "system", "condition": "amount > rules.approval.finance_threshold", "description": "Auto-escalated when amount exceeds finance threshold" }, "finance_approve": { "from": "pending_finance", "to": "approved", "actor": "finance_manager", "description": "Finance manager approves high-value expense" }, "auto_approve": { "from": "manager_approved", "to": "approved", "actor": "system", "condition": "amount <= rules.approval.finance_threshold", "description": "Auto-approved when under finance threshold" }, "reject": { "from": [ "submitted", "pending_finance" ], "to": "rejected", "actor": [ "manager", "finance_manager" ], "requires": "rejection_reason", "description": "Reviewer rejects with mandatory reason" }, "revise": { "from": "rejected", "to": "draft", "actor": "employee", "description": "Employee revises and can resubmit rejected expense" }, "process_payment": { "from": "approved", "to": "paid", "actor": "payment_system", "description": "System processes reimbursement via payroll" } } }, "rules": { "approval": { "finance_threshold": 1000, "max_single_expense": 50000 }, "receipt": { "required_above": 25, "accepted_formats": [ "pdf", "png", "jpg", "jpeg" ], "max_size_mb": 10 }, "submission": { "max_age_days": 90, "duplicate_detection": true }, "security": { "rate_limit": { "window_seconds": 3600, "max_requests": 20, "scope": "per_user" } }, "audit": { "log_all_transitions": true, "retention_days": 2555 } }, "sla": { "manager_review": { "transition": "submit", "max_duration": "48h", "escalation": "notify_department_head", "description": "Manager must review within 48 business hours" }, "finance_review": { "transition": "escalate_to_finance", "max_duration": "72h", "escalation": "notify_cfo", "description": "Finance must review within 72 business hours" }, "payment_processing": { "transition": "manager_approve", "max_duration": "5d", "description": "Reimbursement processed within 5 business days of final approval" }, "overall_completion": { "from_state": "submitted", "to_state": "paid", "max_duration": "30d", "description": "End-to-end from submission to payment within 30 calendar days" } }, "flows": { "submit_expense": { "description": "Employee submits a new expense report", "steps": [ { "id": "validate", "action": "validate_fields", "actor": "employee", "description": "Validate all required fields and formats" }, { "id": "check_receipt", "action": "check_receipt_required", "actor": "system", "condition": "amount > rules.receipt.required_above", "description": "Require receipt upload if amount exceeds $25", "on_fail": "receipt_missing", "documents": [ "receipt" ] }, { "id": "check_duplicates", "action": "detect_duplicate_expense", "actor": "system", "condition": "rules.submission.duplicate_detection == true", "description": "Warn if a similar expense already exists" }, { "id": "submit", "action": "transition_state", "actor": "employee", "description": "Move status from draft → submitted" }, { "id": "notify_manager", "action": "send_notification", "actor": "system", "template": "expense_submitted_for_review", "description": "Email the direct manager that a new expense needs review" }, { "id": "emit_submitted", "action": "emit", "event": "expense.submitted" } ] }, "manager_review": { "description": "Manager reviews and approves or rejects the expense", "steps": [ { "id": "load_expense", "action": "load_expense_with_receipt", "actor": "manager", "description": "Manager opens the expense report with all attachments" }, { "id": "verify_business_purpose", "action": "review_justification", "actor": "manager", "description": "Verify the expense has a legitimate business purpose" }, { "id": "decide", "action": "approve_or_reject", "actor": "manager", "description": "Manager approves or rejects (rejection requires reason)", "on_fail": "rejection_flow" }, { "id": "check_threshold", "action": "check_finance_threshold", "actor": "system", "condition": "amount > rules.approval.finance_threshold", "description": "Route to finance if over $1,000, otherwise auto-approve" }, { "id": "emit_reviewed", "action": "emit", "event": "expense.manager_reviewed" } ] }, "finance_review": { "description": "Finance manager reviews high-value expenses", "steps": [ { "id": "load_expense", "action": "load_expense_with_history", "actor": "finance_manager", "description": "Review expense with audit trail and manager approval" }, { "id": "verify_budget", "action": "check_department_budget", "actor": "finance_manager", "description": "Verify department has remaining budget for this expense" }, { "id": "decide", "action": "approve_or_reject", "actor": "finance_manager", "description": "Finance approves or rejects", "on_fail": "rejection_flow" }, { "id": "emit_approved", "action": "emit", "event": "expense.approved" } ] }, "rejection_flow": { "description": "Expense rejected by a reviewer", "trigger": "reviewer clicks reject", "steps": [ { "id": "require_reason", "action": "validate_rejection_reason", "description": "Rejection reason is mandatory" }, { "id": "transition", "action": "transition_state", "description": "Move status to rejected" }, { "id": "notify_employee", "action": "send_notification", "actor": "system", "template": "expense_rejected", "description": "Email the employee with rejection reason" }, { "id": "emit_rejected", "action": "emit", "event": "expense.rejected" } ] }, "payment_flow": { "description": "System processes approved expense for reimbursement", "steps": [ { "id": "queue_payment", "action": "create_payment_record", "actor": "payment_system", "description": "Create reimbursement entry in payroll system" }, { "id": "process", "action": "execute_payment", "actor": "payment_system", "description": "Process via direct deposit or payroll", "on_fail": "payment_failed" }, { "id": "transition", "action": "transition_state", "description": "Move status to paid" }, { "id": "notify_employee", "action": "send_notification", "actor": "system", "template": "expense_reimbursed", "description": "Confirm reimbursement to the employee" }, { "id": "emit_paid", "action": "emit", "event": "expense.paid" } ] }, "receipt_missing": { "description": "Receipt required but not attached", "trigger": "amount > rules.receipt.required_above AND no receipt uploaded", "steps": [ { "action": "show_error", "error": "EXPENSE_RECEIPT_REQUIRED" } ] }, "payment_failed": { "description": "Payment processing failed", "trigger": "payment system returns error", "steps": [ { "action": "emit", "event": "expense.payment_failed" }, { "action": "send_notification", "actor": "system", "template": "payment_failed_alert", "description": "Alert finance team of payment failure" }, { "action": "show_error", "error": "EXPENSE_PAYMENT_FAILED" } ] } }, "outcomes": { "expense_submitted": { "priority": 10, "transaction": true, "given": [ "user is authenticated", { "field": "title", "operator": "exists", "description": "Title is provided" }, { "field": "amount", "operator": "gte", "value": 0.01, "description": "Amount is at least $0.01" }, { "field": "amount", "operator": "lte", "value": 50000, "description": "Amount does not exceed $50,000" }, { "field": "category", "operator": "in", "value": [ "travel", "meals", "supplies", "software", "equipment", "other" ], "description": "Category is a valid option" }, { "field": "date_incurred", "operator": "gte", "value": "today - 90 days", "description": "Expense is within the last 90 days" }, { "field": "description", "operator": "gte", "value": 10, "description": "Description has at least 10 characters (minLength)" }, { "field": "receipt", "operator": "exists", "description": "Receipt is attached when amount > $25", "when": "amount > 25" }, { "field": "request_count", "operator": "lte", "value": 20, "description": "Not rate limited (max 20 per hour per user)" } ], "then": [ "status transitions from draft to submitted", "direct manager is notified via email", "expense.submitted event is emitted", "all state transitions are logged for audit (actor, timestamp, IP)" ], "result": "expense appears in manager's review queue" }, "manager_approves_under_threshold": { "priority": 10, "transaction": true, "given": [ { "field": "reviewer_role", "operator": "eq", "value": "manager", "description": "Reviewer has manager role for the submitting employee" }, { "field": "status", "operator": "eq", "value": "submitted", "description": "Expense is in submitted status" }, { "field": "amount", "operator": "lte", "value": 1000, "description": "Amount is at or below finance threshold" } ], "then": [ "status transitions to approved (auto-skip finance)", "expense.manager_reviewed event is emitted" ], "result": "expense is queued for payment" }, "manager_approves_over_threshold": { "priority": 10, "transaction": true, "given": [ { "field": "reviewer_role", "operator": "eq", "value": "manager", "description": "Reviewer has manager role" }, { "field": "status", "operator": "eq", "value": "submitted" }, { "field": "amount", "operator": "gt", "value": 1000, "description": "Amount exceeds finance threshold" } ], "then": [ "status transitions to pending_finance", "expense.manager_reviewed event is emitted" ], "result": "expense is escalated to finance for review" }, "finance_approves": { "priority": 10, "transaction": true, "given": [ { "field": "reviewer_role", "operator": "eq", "value": "finance_manager" }, { "field": "status", "operator": "eq", "value": "pending_finance" }, "department has remaining budget for this expense" ], "then": [ "status transitions to approved", "expense.approved event is emitted" ], "result": "expense is queued for payment processing" }, "expense_rejected": { "priority": 5, "error": "EXPENSE_INVALID_TRANSITION", "transaction": true, "given": [ { "field": "reviewer_role", "operator": "in", "value": [ "manager", "finance_manager" ] }, { "field": "status", "operator": "in", "value": [ "submitted", "pending_finance" ] }, { "field": "rejection_reason", "operator": "exists", "description": "Rejection reason is mandatory" } ], "then": [ "status transitions to rejected", "employee is notified with rejection reason", "expense.rejected event is emitted" ], "result": "employee can revise (status back to draft) and resubmit" }, "payment_processed": { "priority": 10, "transaction": true, "given": [ { "field": "status", "operator": "eq", "value": "approved" }, "payment system is available" ], "then": [ "reimbursement is created in payroll system", "status transitions to paid", "employee is notified of reimbursement", "expense.paid event is emitted" ], "result": "employee receives reimbursement via direct deposit or payroll" }, "payment_failed": { "error": "EXPENSE_PAYMENT_FAILED", "given": [ "payment system returns error" ], "then": [ "expense.payment_failed event is emitted", "finance team is alerted" ], "result": "expense stays in approved status, finance investigates", "priority": 20 }, "sla_breached": { "given": [ { "field": "time_in_submitted", "operator": "gt", "value": "48h", "description": "Manager review exceeds 48 hours" }, { "field": "time_in_pending_finance", "operator": "gt", "value": "72h", "description": "Finance review exceeds 72 hours" }, { "field": "time_since_submitted", "operator": "gt", "value": "30d", "description": "End-to-end exceeds 30 days" } ], "then": [ "expense.sla_breached event is emitted", "escalation notification sent (department head or CFO)" ], "result": "escalation path activated per SLA rules", "priority": 21 } }, "errors": [ { "code": "EXPENSE_VALIDATION_ERROR", "status": 422, "message": "Please check your input and try again", "retry": true }, { "code": "EXPENSE_RECEIPT_REQUIRED", "status": 422, "message": "A receipt is required for expenses over $25", "retry": true }, { "code": "EXPENSE_DUPLICATE_DETECTED", "status": 409, "message": "A similar expense already exists. Please review before submitting.", "retry": true }, { "code": "EXPENSE_NOT_FOUND", "status": 404, "message": "Expense report not found", "retry": false }, { "code": "EXPENSE_INVALID_TRANSITION", "status": 422, "message": "This action is not allowed in the current status", "retry": false }, { "code": "EXPENSE_UNAUTHORIZED", "status": 403, "message": "You do not have permission to perform this action", "retry": false }, { "code": "EXPENSE_BUDGET_EXCEEDED", "status": 422, "message": "This expense would exceed the department budget. Please contact finance.", "retry": false }, { "code": "EXPENSE_PAYMENT_FAILED", "status": 500, "message": "Payment processing failed. Finance has been notified.", "retry": false }, { "code": "EXPENSE_RATE_LIMITED", "status": 429, "message": "Too many submissions. Please try again later.", "retry": false } ], "events": [ { "name": "expense.submitted", "description": "New expense submitted for approval", "payload": [ "expense_id", "submitted_by", "amount", "category", "timestamp" ] }, { "name": "expense.manager_reviewed", "description": "Manager completed review (approve or reject)", "payload": [ "expense_id", "reviewer_id", "decision", "amount", "timestamp" ] }, { "name": "expense.approved", "description": "Expense fully approved (all levels)", "payload": [ "expense_id", "approved_by", "amount", "timestamp" ] }, { "name": "expense.rejected", "description": "Expense rejected at any level", "payload": [ "expense_id", "rejected_by", "reason", "amount", "timestamp" ] }, { "name": "expense.paid", "description": "Reimbursement processed successfully", "payload": [ "expense_id", "user_id", "amount", "payment_method", "timestamp" ] }, { "name": "expense.payment_failed", "description": "Reimbursement processing failed", "payload": [ "expense_id", "user_id", "amount", "error_detail", "timestamp" ] }, { "name": "expense.sla_breached", "description": "An SLA deadline was exceeded", "payload": [ "expense_id", "sla_name", "expected_duration", "actual_duration", "timestamp" ] } ], "related": [ { "feature": "login", "type": "required", "reason": "Users must be authenticated to submit expenses" }, { "feature": "roles-permissions", "type": "recommended", "reason": "Manager and finance roles determine who can approve" }, { "feature": "notifications", "type": "recommended", "reason": "Email and in-app notifications at each step" }, { "feature": "file-upload", "type": "required", "reason": "Receipt upload functionality" }, { "feature": "audit-log", "type": "recommended", "reason": "All transitions logged for compliance" } ], "ui_hints": { "screens": { "submit": { "layout": "single_column", "max_width": "600px", "title": "Submit Expense", "fields_order": [ "title", "amount", "currency", "category", "date_incurred", "description", "receipt" ], "actions": { "primary": { "label": "Submit for Approval", "type": "submit" }, "secondary": [ { "label": "Save Draft", "action": "save_draft" } ] } }, "review": { "layout": "two_column", "title": "Review Expense", "left_column": [ "title", "amount", "currency", "category", "date_incurred", "description" ], "right_column": [ "receipt", "status", "submitted_by" ], "actions": { "primary": { "label": "Approve", "type": "submit", "style": "success" }, "secondary": [ { "label": "Reject", "action": "reject", "style": "danger", "requires_reason": true } ] } }, "list": { "layout": "table", "title": "My Expenses", "columns": [ "title", "amount", "category", "date_incurred", "status" ], "filters": [ "status", "category", "date_range" ], "sort_default": "date_incurred_desc" } }, "accessibility": { "aria_live_region": true }, "loading": { "disable_button": true, "show_spinner": true, "prevent_double_submit": true } }, "agi": { "goals": [ { "id": "compliant_expense_processing", "description": "Process expense reports accurately while enforcing company policy and maintaining full audit trails", "success_metrics": [ { "metric": "processing_time", "target": "< 48h from submission to reimbursement", "measurement": "Time from employee submission to payment execution" }, { "metric": "policy_violation_rate", "target": "0%", "measurement": "Expenses approved that violate company policy" }, { "metric": "duplicate_detection_rate", "target": ">= 99%", "measurement": "Percentage of duplicate expenses caught before approval" } ], "constraints": [ { "type": "regulatory", "description": "All expenses above threshold require receipts and multi-level approval", "negotiable": false }, { "type": "cost", "description": "Processing cost per expense report must not exceed 2% of average expense amount", "negotiable": true } ] } ], "autonomy": { "level": "supervised", "human_checkpoints": [ "before approving expenses above the finance threshold", "before overriding a policy violation flag", "before processing reimbursement to a new bank account" ], "escalation_triggers": [ "pending_approvals > 50", "duplicate_expense_flags > 5" ] }, "safety": { "action_permissions": [ { "action": "auto_approve_under_limit", "permission": "autonomous", "max_auto_decisions": 10 }, { "action": "approve_over_limit", "permission": "human_required" }, { "action": "flag_duplicate", "permission": "autonomous" }, { "action": "process_reimbursement", "permission": "supervised" }, { "action": "override_policy_violation", "permission": "human_required" }, { "action": "modify_approval_thresholds", "permission": "human_required" } ] }, "explainability": { "log_decisions": true, "reasoning_depth": "full", "audit_events": [ { "decision": "expense_approved", "must_log": [ "expense_id", "amount", "category", "approver", "policy_rule", "timestamp" ] }, { "decision": "expense_rejected", "must_log": [ "expense_id", "amount", "reason", "reviewer", "timestamp" ] }, { "decision": "policy_override", "must_log": [ "expense_id", "original_decision", "override_reason", "authorizer", "timestamp" ] }, { "decision": "duplicate_flagged", "must_log": [ "expense_id", "matched_expense_id", "similarity_score", "timestamp" ] } ] } } }