Approvals, AI & Insights
The sign-off layer: approval queue, AI document approvals, the read-only AI assistant and anomaly detection.
The platform's trust rule
Rule
The AI proposes, a human approves
Nothing the AI or the automation produces enters the ledger until a person confirms it. This is enforced in the architecture, not just the interface.
The four surfaces
| Page | Route | Roles | Purpose |
|---|---|---|---|
| Approval Queue | /dashboard/approval-queue | CEO; actions by CEO, CFO, COO | Financial sign-off inbox — mainly demurrage invoices |
| AI Approvals | /dashboard/approvals | CEO, CFO | Upload documents, review AI extractions, commit to the ledger |
| AI Fleet Assistant | /dashboard/ai-assistant | CEO, CFO | Read-only assistant: reports, lookups, document processing |
| Anomaly Detection | /dashboard/insights/anomaly | CEO, CFO | Flags KPI anomalies and recommends actions |
Approval Queue
The queue lists rows with status PENDING_APPROVAL. Two kinds of item appear: a draft demurrage invoice raised by the demurrage engine, and a write proposal from the AI assistant.
| Action | Effect |
|---|---|
| Approve | For a demurrage invoice: issues it and posts the GL entry (Dr 1200 AR / Cr 4100 Demurrage Income) in one transaction. The queue row becomes APPROVED. |
| Reject | Queue row becomes REJECTED. No document or GL effect. For demurrage this means not billed, so the container can be re-billed later. |
| Escalate | Queue row becomes ESCALATED. No document effect. |
Selecting an item shows who requested it, the department, the amount, when it was submitted and any notes. Approving an AI write proposal commits the document through the same handler used by AI Approvals and Telegram.
AI → Approval QueueAI Approvals — document ingestion
Upload a document and the AI extracts structured data. You review and confirm before it enters the ledger.
| Document | Becomes | On approval |
|---|---|---|
| Sales invoice | sales_invoice plus lines | Inserted ISSUED and posted: Dr 1200 AR / Cr 4000 Revenue + 2300 Tax |
| Expense receipt | trip_expense (if a trip is chosen) or petty_cash_transaction | Inserted and posted: Dr 5000 / Cr 1010 |
| Payment receipt | customer receipt (an invoice must be chosen) | Inserted and posted: Dr 1010 / Cr 1200 |
| Purchase order | purchase_order | Inserted APPROVED — no GL |
| Sales order | sales_order | Inserted APPROVED — no GL |
| Bill of lading / customs declaration | customs_document | Enriched with doc number and date — no GL |
| Waybill / demurrage statement | Register or audit only | No GL |
- 01
Upload
PDF, JPEG, PNG, TIFF, XLSX or XLS — maximum 10 MB. Duplicates are detected by file hash, so the same file cannot be processed twice.
- 02
Wait for extraction
The AI worker OCRs the file and extracts JSON, then sets the task to PENDING_APPROVAL. It retries up to three times, then marks the task FAILED.
- 03
Review
The approval card shows OCR and AI confidence badges, a source preview, editable extracted fields and read-only line items.
- 04
Resolve the entity
Always a human decision. Invoice or sales order → customer. Purchase order → vendor. Payment receipt → the invoice being paid. Expense receipt → optional trip plus expense category.
- 05
Approve or reject
Approving commits the record and the GL entry, then marks any matching queue row resolved. Every approval writes an audit entry with the journal reference.
AI → AI ApprovalsAI Fleet Assistant
A read-only assistant that answers questions and produces reports. The upload dropdown offers Auto-detect, Sales Invoice, Purchase Order, Expense Receipt, Payment Receipt and Sales Order.
| It can | It never |
|---|---|
| Look up invoices, POs, sales orders, trips, vehicles, waybills and containers | Write SQL — it only calls a fixed, role-filtered set of tools |
| Report on inventory, sales, finance, operations and port data | Change data — if you ask it to create something it files a pending approval instead |
| Generate downloadable reports such as trip profitability, P&L, balance sheet, sales and inventory | Invent data — when a tool finds nothing it says so |
| Queue a document you send it for extraction | Post anything to the ledger |
Sample prompts: Show trip profitability this month. Generate P&L for last quarter. What is our outstanding receivables? Show inventory valuation.
Note
Guardrails
There is a per-user rate limit and a five-step tool loop cap, so the assistant cannot run away with a request.
Anomaly Detection
Four sections, all computed from KPI history. None of them has a ledger effect.
| Section | What it does |
|---|---|
| Anomaly Alerts | Z-score of the latest value against the last 30 days: |z| > 3 high, > 2 medium, > 1 low |
| Insight Cards | Week-over-week and 30-day movements, with cost metrics inverted so a rise in expenses or receivables reads as negative |
| Trend Classification | 14-day direction: improving, declining or stable |
| Recommendations | Threshold rules such as cash flow shortfall predicted, profit margin below 10%, high receivables concentration above 30%, underutilised fleet below 60%, expense ratio above 85% |
Insights → Anomaly DetectionBackground automation
| Job | Runs | What it does |
|---|---|---|
| AI worker | Every 2 minutes | OCR and extraction for up to 5 pending uploads |
| Alerts | Every 6 hours | Overdue invoices, low stock, pending approvals and port anomalies become notifications |
| Demurrage scan | Daily at 02:00 | Drafts demurrage invoices and approval queue rows |
Status reference
| Entity | Statuses |
|---|---|
| AI task | PENDING → PROCESSING → PENDING_APPROVAL → COMPLETED or FAILED, or REJECTED |
| Approval queue row | PENDING_APPROVAL → APPROVED, REJECTED or ESCALATED, then RESOLVED for AI items |
Troubleshooting
| Message | Fix |
|---|---|
| Unsupported file type. Please upload PDF, Excel, or image. | Use PDF, JPEG, PNG, TIFF, XLSX or XLS |
| File already uploaded. Use the approval queue to review it. | Review the existing task |
| File exceeds 10 MB limit. | Split or compress the file |
| No text extracted from document / AI response validation failed | Re-upload a clearer copy |
| Task is not pending approval (current status: …) | Refresh the list |
| Task already processed by another user | Refresh |
| Invalid payload: … | Correct the fields, then approve |
| Please select a customer / vendor / invoice … before approving. | Choose the entity from the dropdown |
| Unknown task type: … | Reject and re-upload with an explicit type |
| Approval queue item not found | Refresh the list |
| Rate limit exceeded. Try again in a moment. | Wait and retry |
| No anomalies detected in the last 30 days | Not an error — no action |
Ledger boundary
| Action | Posts? |
|---|---|
| Approval Queue → approve a demurrage invoice | Yes — Dr 1200 AR / Cr 4100 Demurrage Income |
| Approval Queue → reject or escalate | No |
| AI Approvals → approve invoice, expense receipt or payment receipt | Yes |
| AI Approvals → approve PO, sales order, customs, waybill or demurrage statement | No |
| AI Approvals → reject | No |
| AI Assistant — any tool | No (reports only; write intent becomes a proposal) |
| Anomaly Detection | No |
Cheat sheet
- Sign off a demurrage invoice
- AI → Approval Queue → Approve
- Upload a document for extraction
- AI → AI Approvals → upload
- Review and commit an extraction
- AI Approvals → pick the entity → Approve
- Ask a data question or get a report
- AI → AI Fleet Assistant
- See KPI warnings
- Insights → Anomaly Detection
- Create something via the assistant
- Ask it — it files a proposal for approval
Rule
The rule that never changes
The AI never posts. A human approves every ledger effect.