ZATCA Sending Options – Technical Diagrams

This document provides a set of diagrams using Mermaid (wrapped with ::: mermaid blocks) so they render directly in VS Code Markdown preview, without needing a PlantUML server.

You can still copy the logical flows into any diagram tool if needed.

📋 Executive Summary

Core Behavior Rules

🤖 Automatic Mode

When SendingMode = AUTOMATIC, the system sends documents to ZATCA automatically based on the configured trigger:

ON_SAVE: Document sends immediately when user clicks Save
ON_POST: Document sends immediately when user clicks Post
ON_FIRST_PRINT: Document sends on first print (with fallback to Post if never printed)

🖱️ Manual Mode

When SendingMode = MANUAL, user must explicitly click the [Send to ZATCA] button.

🔒 Edit and Post Restrictions Based on Status

|-------------|-----------|-----------|-----------|--------------|

| NOT_SENT | ✅ Yes | ✅ Yes | ✅ Yes | - |

| SENDING | ❌ No | ❌ No | ❌ No | "العملية قيد الإرسال" (Operation in progress) |

| SENT_SUCCESSFULLY | ❌ No | ❌ No | ❌ No | "تم الإرسال بنجاح" (Sent successfully) |

🔄 Retry Logic

Failed documents can be edited to fix validation errors
Failed documents can be retried without editing (manual or automatic based on configuration)
Multiple retry attempts allowed until successful

🎯 Configuration Per Document Scope

Each document type has independent configuration:

ERP Sales Invoice
ERP Credit Note
ERP Advanced Payment
ERP Project Invoice
VAN Sales Invoice
VAN Credit Note

🎯 Quick Reference: ZATCA Flow Decision Tree

1. High-Level Context Diagram

2. Configuration Screen – Class & Data Model

10. Edit Lock Logic – Activity Diagram (User Story 7)

11. Default Seeding on ZATCA Activation – Activity Diagram (User Story 8)

12. Complete ZATCA Flow - Edit, Post, and Send Logic

13. ZATCA Status Lifecycle and Permissions

14. Automatic Sending Configuration Matrix

15. Send Retry Logic (Failed Status Handling)

3. ZATCA Status State Diagram (Simple)

4. Document Scope Enumeration

5. Manual Send – User Story 2

6. Automatic Send on Save – User Story 3

7. Automatic Send on Post – User Story 4

8. Automatic Send on First Print + Fallback on Post – User Story 5

Use and customize these diagrams to fit your exact architecture (sync vs async send, message bus, microservices, etc.).

ZATCA Sending Options – Technical Diagrams ​

📋 Executive Summary ​

Core Behavior Rules ​

🤖 Automatic Mode ​

🖱️ Manual Mode ​

🔒 Edit and Post Restrictions Based on Status ​

🔄 Retry Logic ​

🎯 Configuration Per Document Scope ​

🎯 Quick Reference: ZATCA Flow Decision Tree ​

1. High-Level Context Diagram ​

2. Configuration Screen – Class & Data Model ​

10. Edit Lock Logic – Activity Diagram (User Story 7) ​

11. Default Seeding on ZATCA Activation – Activity Diagram (User Story 8) ​

12. Complete ZATCA Flow - Edit, Post, and Send Logic ​

13. ZATCA Status Lifecycle and Permissions ​

14. Automatic Sending Configuration Matrix ​

15. Send Retry Logic (Failed Status Handling) ​

3. ZATCA Status State Diagram (Simple) ​

4. Document Scope Enumeration ​

5. Manual Send – User Story 2 ​

6. Automatic Send on Save – User Story 3 ​

7. Automatic Send on Post – User Story 4 ​

8. Automatic Send on First Print + Fallback on Post – User Story 5 ​