Workflow & Roles

Workflow & Roles

---

Invoice Lifecycle States

                    ┌──────────────┐
                    │   pending    │
                    └──────┬───────┘
                           │ (auditor picks up)
                    ┌──────▼───────┐
                    │ under_review │
                    └──────┬───────┘
                           │
              ┌────────────┼────────────┐
              │            │            │
       ┌──────▼──┐  ┌──────▼──┐  ┌─────▼────┐
       │ approved │  │ rejected │  │ queried  │
       └──────┬───┘  └──────┬──┘  └─────┬────┘
              │             │           │
       ┌──────▼──┐  ┌──────▼────┐ ┌────▼──────────┐
       │  paid   │  │resubmitted│ │vendor_responded│
       └─────────┘  └──────┬────┘ └────┬───────────┘
                           │           │
                    ┌──────▼───────────▼┐
                    │   under_review    │
                    └───────────────────┘

State Descriptions

State	Description
pending	Invoice received, not yet reviewed
under_review	Auditor is actively reviewing; validation engine has run
approved	All checks passed or findings resolved; cleared for payment
rejected	Significant issues found; invoice sent back to vendor
queried	Specific questions sent to vendor about certain line items
vendor_responded	Vendor has replied to query; awaiting auditor re-review
resubmitted	Vendor submitted a corrected invoice after rejection
paid	Invoice approved and payment processed

---

Role-Based Access Control

Roles

Role	Description
Admin	Full system access. Manages organization settings, users, vendors, contracts.
Senior Auditor	Full audit capabilities. Can approve any invoice, waive findings with documented reason.
Auditor	Standard audit role. Can review, query, and approve invoices within threshold.
Viewer	Read-only access. Can view invoices, findings, dashboards, and reports.

Permission Matrix

Action	Admin	Senior Auditor	Auditor	Viewer
Manage users	Yes	No	No	No
Manage vendors	Yes	Yes	No	No
Manage contracts	Yes	Yes	No	No
Create/edit rate cards	Yes	Yes	No	No
Submit invoices	Yes	Yes	Yes	No
Run validation	Yes	Yes	Yes	No
Review findings	Yes	Yes	Yes	Yes (read-only)
Approve invoices (below threshold)	Yes	Yes	Yes	No
Approve invoices (above threshold)	Yes	Yes	No	No
Reject invoices	Yes	Yes	Yes	No
Query vendor	Yes	Yes	Yes	No
Waive findings	Yes	Yes	No	No
View dashboard	Yes	Yes	Yes	Yes
Generate reports	Yes	Yes	Yes	No
View audit trail	Yes	Yes	Yes	No
Export data	Yes	Yes	Yes	No
Manage organization settings	Yes	No	No	No

---

Approval Thresholds

Configurable per organization:

Invoice Amount	Required Approval
Under R50,000	Any Auditor
R50,000 - R500,000	Senior Auditor
Over R500,000	Two approvals (dual sign-off)

These thresholds are stored in Organization.settings and can be adjusted by the Admin.

Dual Sign-Off Flow

For high-value invoices requiring two approvals:

1. First approver reviews and approves → status stays "under_review"
2. System records first approval in audit log
3. Second approver (different user) reviews and approves → status becomes "approved"
4. Both approvers recorded in audit log

---

Query Workflow

When an auditor queries a vendor about specific findings:

Steps

1. Auditor initiates query

   • Selects specific findings to query
   • Writes a message to the vendor
   • Invoice status changes to queried

2. System records the query

   • Query details stored with references to specific findings
   • Timestamp and auditor recorded in audit log

3. Vendor notification (configurable)

   • Option A: Email sent to vendor contact with query details
   • Option B: Vendor logs into portal to see queries (post-MVP)
   • Option C: Manual — auditor handles communication externally

4. Vendor response captured

   • Response text recorded against the query
   • Supporting documents can be attached
   • Invoice status changes to vendor_responded

5. Auditor re-reviews

   • Reviews vendor response alongside original findings
   • Can approve, reject, or query further
   • All actions recorded in audit log

Query Data Model

InvoiceQuery
├── id
├── invoiceId → Invoice
├── findingIds (JSON array — which findings this query relates to)
├── queryMessage (text sent to vendor)
├── queriedBy → User
├── queriedAt
├── vendorResponse (text — vendor's reply)
├── respondedAt
├── attachments (JSON array — file references)
├── status (open | responded | resolved)
└── resolvedBy → User

---

Finding Resolution Workflow

Each validation finding has its own lifecycle:

open → acknowledged → resolved
                   → waived (with mandatory reason)

Status	Description
open	Finding detected by validation engine, not yet addressed
acknowledged	Auditor has seen the finding and is investigating
resolved	Issue was corrected (vendor resubmitted) or explained satisfactorily
waived	Auditor accepts the discrepancy with documented justification

Waiver Requirements

Waivers are a sensitive action — they mean accepting a known discrepancy. Requirements:

• Only Senior Auditor or Admin can waive findings
• A written reason is mandatory
• The waiver is permanently recorded in the audit log
• Waivers are highlighted in monthly reports
• Organizations can set a maximum waiver amount per period (configurable)

---

Notification System (MVP Scope)

In-App Notifications

Event	Notified Role
New invoice submitted	Auditor, Senior Auditor
Critical findings detected	Senior Auditor
Invoice queried	(External — vendor contact)
Vendor responded to query	Original querying auditor
Invoice pending approval (> 48 hrs)	Senior Auditor
Monthly report ready	Admin, Senior Auditor

Email Notifications (Optional, Configurable)

• Can be enabled/disabled per notification type
• Digest mode available (daily summary instead of real-time)