Standalone ARM — Process Flows¶
1. Overview¶
This document describes end-to-end process flows for every major ARM operation. These flows are derived from the current implementations (Saint Edwards, Al Faisal, Pymble) and generalized into the standalone 3-layer architecture.
2. Master Billing Process (4×4 Framework)¶
The ARM 4×4 Framework defines the universal billing lifecycle:
4 Entities × 4 Processes = Complete Billing Lifecycle
Entities: Debtor → Items → Transactions → Payments
Processes: Setup → Configure → Generate → Process
Full Lifecycle Flow¶
┌─────────────────────────────────────────────────────────────────┐
│ PROCESS 1: SETUP │
│ │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────────┐ │
│ │ Import │──▶│ Create │──▶│ Import │──▶│ Configure │ │
│ │ Students │ │ Debtors │ │ Items │ │ Billing Cycle│ │
│ └──────────┘ └──────────┘ └──────────┘ └──────────────┘ │
└───────────────────────────┬─────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ PROCESS 2: CONFIGURE │
│ │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────────┐ │
│ │ Segment │──▶│ Select │──▶│ Map Items│──▶│ Add │ │
│ │ Items │ │ Families │ │ to Years │ │ Exceptions │ │
│ └──────────┘ └──────────┘ └──────────┘ └──────────────┘ │
│ │ │
│ ┌───────▼────────┐ │
│ │ Review & │ │
│ │ Approve │ │
│ └────────────────┘ │
└───────────────────────────┬─────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ PROCESS 3: GENERATE │
│ │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────────┐ │
│ │ Generate │──▶│ Generate │──▶│ Generate │──▶│ Send to │ │
│ │ Invoices/│ │ PDFs │ │ Payment │ │ Parents │ │
│ │ Orders │ │ │ │ Links │ │ (Email) │ │
│ └──────────┘ └──────────┘ └──────────┘ └──────────────┘ │
│ │ │
│ ┌───────▼────────┐ │
│ │ Sync to ERP │ │
│ └────────────────┘ │
└───────────────────────────┬─────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ PROCESS 4: PROCESS │
│ │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────────┐ │
│ │ Parent │──▶│ Create │──▶│ Process │──▶│ Record │ │
│ │ Sets Up │ │ RPS │ │ Payments │ │ & Reconcile │ │
│ │ Pay Plan │ │ Records │ │ (eway/ │ │ │ │
│ │ (Portal) │ │ │ │ ABA) │ │ │ │
│ └──────────┘ └──────────┘ └──────────┘ └──────────────┘ │
└─────────────────────────────────────────────────────────────────┘
3. Detailed Process Flows¶
3.1 Student/Debtor Setup¶
START
│
├── [SIS Integration?]
│ │
│ ├── YES (API) ──▶ ARM calls SIS API ──▶ Import students + families
│ │
│ ├── YES (File) ──▶ Admin uploads CSV/Excel ──▶ ARM parses file
│ │ ──▶ Validation errors?
│ │ ├── YES ──▶ Show errors ──▶ Fix & retry
│ │ └── NO ──▶ Continue
│ │
│ └── YES (Wizard) ──▶ Step-by-step guided import (Saint Edwards pattern)
│
│
├── [Existing Debtors in ERP?]
│ │
│ ├── YES ──▶ Sync debtors from ERP (NetSuite/Dynamics)
│ │ ──▶ Match students to debtors
│ │
│ └── NO ──▶ Create debtors manually in ARM
│
│
├── Validate data:
│ ├── Every student has a debtor
│ ├── Every debtor has at least one student
│ ├── Year levels are valid
│ ├── Email addresses present
│ └── No duplicate student/debtor codes
│
│
└── Debtors and Students ready for billing
END
3.2 Billing Configurator Flow¶
START
│
├── Create or clone billing cycle
│ ├── New ──▶ Enter cycle name, dates, frequency
│ └── Clone ──▶ Select prior cycle ──▶ Copy all settings
│
├── Tab 2: Define item segments
│ └── Group items by billing engine type
│
├── Tab 3: Select items for this cycle
│ └── Check/uncheck items from catalog
│
├── Tab 4: Select families
│ └── Auto-select all active ──▶ Exclude if needed
│
├── Tab 5: Map items to year levels
│ └── Fill matrix: year × item = amount
│
├── Tab 6: Add exceptions
│ ├── Per-student amount overrides
│ ├── Per-student item exclusions
│ └── Per-student additional items
│
├── Tab 7: Configure payment settings
│ ├── Enable payment methods
│ ├── Set frequencies
│ ├── Set date mode (flexible/fixed)
│ └── Configure opening balance handling
│
├── Tab 8: Review & Approve
│ ├── View summary totals
│ ├── View breakdown by segment / year level
│ ├── Validate (no errors/warnings)
│ │ ├── Errors ──▶ Must fix before approval
│ │ └── Warnings ──▶ Can acknowledge and proceed
│ └── Approve ──▶ Status = "approved"
│
└── Ready for generation
END
3.3 Transaction Generation Flow¶
START (Billing cycle is approved)
│
├── [Transaction Type?]
│ │
│ ├── Invoice ──▶ Generate one invoice per debtor
│ │ ├── Line items from billing instructions applied to this debtor
│ │ ├── Apply discounts
│ │ ├── Calculate tax
│ │ ├── Set due date (cycle start + payment terms)
│ │ └── Status = "pending"
│ │
│ └── Billing Order ──▶ Generate one billing order per debtor
│ ├── Line items from billing instructions
│ ├── Apply discounts
│ ├── Include opening balance (if configured)
│ ├── Include optional items (building levy, if opted in)
│ ├── Status = "pending"
│ └── Billing order is NOT an accounting document
│ (actual invoices created later from parent portal)
│
├── Generate PDF for each transaction
│ ├── Use tenant email template
│ ├── Include line items, totals, payment link
│ └── Store PDF (File Record)
│
├── Generate unique payment portal link per transaction
│ └── /portal/pay/{encrypted_transaction_ref}
│
├── Email distribution
│ ├── For each debtor:
│ │ ├── Merge template: debtor name, amount, due date, link
│ │ ├── Attach PDF
│ │ └── Send email
│ │
│ ├── Log email delivery status
│ └── Report: X sent, Y failed, Z bounced
│
├── Sync to ERP
│ ├── [Invoice mode] Push invoices to ERP
│ └── [Billing Order mode] No ERP push yet (invoices created later)
│
└── Billing cycle status = "active"
END
3.4 Parent Payment Portal Flow¶
START (Parent receives email with payment link)
│
├── Parent clicks payment link
│
├── [Authentication required?]
│ │
│ ├── OTP ──▶ Enter debtor code + email
│ │ ──▶ Receive OTP via email
│ │ ──▶ Enter OTP
│ │ ──▶ Authenticated
│ │
│ └── SSO/JWT ──▶ Already authenticated via external portal
│ ──▶ Validated via JWT
│
├── Portal Dashboard
│ ├── View outstanding balance
│ ├── View line items (fees, discounts)
│ └── View optional items (building levy selection)
│
├── [Optional Items?]
│ ├── Building Levy ──▶ Opt in / Opt out
│ └── Other optional items ──▶ Select / Deselect
│
├── Select Payment Method
│ │
│ ├── Credit Card ──▶ Enter card details (tokenized via eway)
│ │
│ ├── Direct Debit ──▶ Enter BSB + Account Number
│ │
│ ├── B Pay ──▶ Display biller code + reference
│ │ ──▶ Parent pays via their bank (no further portal action)
│ │
│ ├── Edstart ──▶ Redirect to Edstart application
│ │
│ └── Annual (Full Payment) ──▶ Pay full amount now
│ ├── [Annual Discount configured?]
│ │ ├── YES ──▶ Apply discount (e.g., 2.5%)
│ │ └── NO ──▶ Full amount
│ └── Process immediately via eway
│
├── [Payment Method = Credit Card or Direct Debit]
│ │
│ ├── Select Payment Frequency
│ │ ├── Weekly / Fortnightly / Monthly / Term / Annual
│ │ └── Show installment amount and dates
│ │
│ ├── [Date Mode = Flexible?]
│ │ ├── YES ──▶ Parent selects payment dates
│ │ └── NO ──▶ Fixed dates displayed
│ │
│ ├── Review Payment Plan Summary
│ │ ├── Total amount
│ │ ├── Number of installments
│ │ ├── Amount per installment
│ │ ├── Payment dates
│ │ └── Payment method
│ │
│ └── Confirm ──▶ Create Recurrence + RPS records
│
├── [Billing Order mode?]
│ ├── Create actual Invoice from Billing Order
│ ├── Mark Billing Order as "Paid from Portal"
│ ├── Set is_closed = true (prevents duplicate processing)
│ └── Push Invoice to ERP
│
└── Confirmation page + email receipt
END
3.5 RPS Payment Processing — Credit Card (eway)¶
START (Daily scheduled job — configurable time per tenant)
│
├── Query RPS records:
│ ├── payment_method = "credit_card"
│ ├── processing_date <= today
│ ├── status = "pending"
│ └── ORDER BY processing_date ASC
│
├── For each RPS record (processed sequentially or in batches):
│ │
│ ├── Retrieve encrypted card token from Recurrence
│ │
│ ├── [Token expired?]
│ │ ├── YES ──▶ Mark RPS "failed", reason = "card_expired"
│ │ │ ──▶ Send "card expiring" notification to parent
│ │ │ ──▶ Skip to next RPS
│ │ └── NO ──▶ Continue
│ │
│ ├── Call eway API: POST /Transaction
│ │ ├── CustomerTokenID
│ │ ├── Amount (cents)
│ │ ├── InvoiceReference
│ │ └── TransactionType = "Recurring"
│ │
│ ├── [eway Response]
│ │ │
│ │ ├── ResponseCode = "00" (Approved)
│ │ │ ├── Update RPS status = "processed"
│ │ │ ├── Set gateway_reference = TransactionID
│ │ │ ├── Set authorization_code = "00"
│ │ │ ├── Set processed_at = now()
│ │ │ ├── Create Payment Record
│ │ │ ├── Update Transaction.amount_paid
│ │ │ ├── [Transaction fully paid?]
│ │ │ │ ├── YES ──▶ Transaction.status = "paid"
│ │ │ │ └── NO ──▶ Transaction.status = "partially_paid"
│ │ │ ├── Sync payment to ERP
│ │ │ └── Log success in audit trail
│ │ │
│ │ ├── ResponseCode = "05", "51" (Declined)
│ │ │ ├── Update RPS status = "failed"
│ │ │ ├── Set failure_code + failure_reason
│ │ │ ├── Increment retry_count
│ │ │ ├── [retry_count < max_retries?]
│ │ │ │ ├── YES ──▶ Schedule retry (next business day)
│ │ │ │ └── NO ──▶ Notify admin for manual resolution
│ │ │ └── Log failure in audit trail
│ │ │
│ │ └── ResponseCode = timeout/network error
│ │ ├── Mark RPS status = "pending" (will retry)
│ │ └── Log error
│ │
│ └── Next RPS record
│
├── Generate daily processing report
│ ├── Total processed: X ($Y)
│ ├── Total failed: X ($Y)
│ └── Failures by reason code
│
└── Send report to admin
END
3.6 RPS Payment Processing — Direct Debit (ABA)¶
START (Scheduled job — configurable per tenant, typically weekly or per-term)
│
├── Query RPS records:
│ ├── payment_method = "direct_debit"
│ ├── processing_date within batch window
│ ├── status = "pending"
│ └── ORDER BY debtor_id, processing_date
│
├── Validate bank details for each RPS record
│ ├── BSB format valid (6 digits)
│ ├── Account number present
│ └── Account name present
│
├── Generate ABA file
│ ├── Header record (Type 0):
│ │ ├── Institution BSB
│ │ ├── Institution account number
│ │ ├── File description
│ │ └── Generation date
│ │
│ ├── Detail records (Type 1 — one per RPS):
│ │ ├── Debtor BSB + account
│ │ ├── Amount (cents)
│ │ ├── Transaction code = 13 (external debit)
│ │ ├── Account name
│ │ └── Lodgement reference (transaction number)
│ │
│ └── Footer record (Type 7):
│ ├── Record count
│ ├── Net total amount
│ └── Hash total (sum of BSB numbers)
│
├── Store ABA file (File Record entity)
│
├── Update RPS statuses = "processing"
│
├── Notify admin: "ABA file ready for download"
│
├── Admin downloads ABA file
│
├── Admin submits to bank
│
├── Bank processes (2-3 business days)
│
├── [Bank Response — automated or manual]
│ │
│ ├── [Automated] Bank return file → ARM processes:
│ │ ├── Successful debits → RPS status = "processed", create payments
│ │ └── Dishonoured debits → RPS status = "failed", set reason
│ │
│ └── [Manual] Admin updates RPS records based on bank statement:
│ ├── Mark successful payments → create Payment Records
│ └── Mark failed payments → log failure reason
│
└── Generate reconciliation report
END
3.7 Payment Method Change¶
START (Parent wants to change payment method mid-cycle)
│
├── [Change occurs BEFORE invoices generated]
│ │
│ ├── Update Recurrence:
│ │ ├── New payment method
│ │ ├── New payment details (tokenize if credit card)
│ │ └── Recalculate installments if frequency changes
│ │
│ ├── Delete existing "pending" RPS records
│ │
│ └── Create new RPS records with updated method/amounts/dates
│
│
├── [Change occurs AFTER invoices generated]
│ │
│ ├── Three records must be updated:
│ │ │
│ │ ├── 1. Recurrence record
│ │ │ ├── Update payment_method
│ │ │ └── Update encrypted_payment_details
│ │ │
│ │ ├── 2. All future RPS records (status = "pending")
│ │ │ ├── Update payment_method
│ │ │ └── Recalculate if amounts differ by method
│ │ │
│ │ └── 3. Transaction record
│ │ ├── Update payment method reference
│ │ └── If moving to/from annual: recalculate discount
│ │
│ ├── [Switching TO annual with discount?]
│ │ ├── Calculate discount amount
│ │ ├── Create credit note for discount
│ │ └── Adjust remaining balance
│ │
│ └── [Switching FROM annual?]
│ ├── Remove discount if previously applied
│ └── Generate new installment schedule
│
└── Audit log: who changed, what changed, when
END
3.8 Mid-Year Enrollment¶
START (New student enrolls mid-year)
│
├── Create student record in ARM
│ ├── Import from SIS or manual entry
│ └── Link to existing or new debtor
│
├── Open active billing cycle
│
├── "Add Mid-Year Student" action
│ ├── Select student
│ ├── Set enrollment date
│ └── ARM calculates pro-rated amounts:
│ amount = annual_amount × (remaining / divisible_value)
│
├── Auto-generate billing instructions for the student
│ └── Based on year level → items-to-years matrix
│
├── Admin reviews pro-rated amounts
│ └── Adjust if needed (exception)
│
├── Generate transaction for this student's debtor
│ ├── Include only the new student's items
│ └── Type = Invoice or Billing Order (per tenant config)
│
├── Send email to parent with payment link
│
├── Parent sets up payment plan via portal
│
└── Sync to ERP
END
3.9 Mid-Year Withdrawal¶
START (Student withdraws mid-year)
│
├── Update student status = "withdrawn"
│ └── Set withdrawal_date
│
├── Calculate refund/credit
│ ├── Pro-rate remaining fees
│ └── refund_amount = remaining_periods × per_period_amount
│
├── Cancel all future RPS records for this debtor/student
│ └── Status = "cancelled"
│
├── [Refund due?]
│ ├── YES ──▶ Generate credit note
│ │ ──▶ Process refund (reverse eway or manual)
│ │ ──▶ Sync credit note to ERP
│ └── NO ──▶ Adjust balance only
│
├── [Other students in family still enrolled?]
│ ├── YES ──▶ Recalculate family billing (sibling discount may change)
│ │ ──▶ Adjust remaining RPS amounts
│ └── NO ──▶ Close all billing for this debtor
│
└── Audit log: withdrawal reason, refund amount, action taken
END
3.10 Collection / Overdue Process¶
START (Transaction past due date)
│
├── Automated reminders (configurable schedule):
│ ├── Reminder 1: [PLACEHOLDER: X days] before due date
│ ├── Reminder 2: On due date
│ ├── Reminder 3: [PLACEHOLDER: X days] after due date
│ └── Final notice: [PLACEHOLDER: X days] after due date
│
├── Each reminder:
│ ├── Send email from "reminder" template
│ ├── Log in Email Log
│ └── Flag transaction as "overdue" after due date
│
├── [Payment received after reminder?]
│ ├── YES ──▶ Process normally ──▶ Clear overdue flag
│ └── NO ──▶ Continue escalation
│
├── Admin actions (manual):
│ ├── Call parent
│ ├── Negotiate payment plan
│ ├── Apply late fee (if configured)
│ └── Escalate to management
│
├── [Payment plan agreed?]
│ ├── YES ──▶ Create new Recurrence with agreed terms
│ │ ──▶ Generate new RPS records
│ └── NO ──▶ Further escalation
│
└── Track all actions in audit log
END
3.11 Year-End / Cycle Close¶
START (Billing cycle period ends)
│
├── Run final reconciliation
│ ├── All transactions: paid / outstanding / overdue
│ ├── All RPS records: processed / pending / failed
│ └── Total collected vs total billed
│
├── Process remaining RPS records
│
├── Handle outstanding balances
│ ├── [Carry forward?]
│ │ ├── YES ──▶ Calculate opening balance for next cycle
│ │ └── NO ──▶ Write off or continue collection
│ │
│ └── Generate outstanding balance report
│
├── Close billing cycle
│ └── Status = "closed"
│
├── Archive cycle data
│ └── Snapshot preserved for audit
│
├── [New cycle?]
│ ├── YES ──▶ Clone previous cycle settings ──▶ Start new cycle
│ └── NO ──▶ End
│
└── Generate year-end reports
├── Revenue summary
├── Payment method breakdown
├── Collection rate analysis
└── Debtor aging report
END
4. Process State Diagrams¶
4.1 Billing Cycle States¶
setup ──▶ configuring ──▶ review ──▶ approved ──▶ generating ──▶ active ──▶ closed
│ │
◀────────────────────────┘
(rejected — return to configuring)
4.2 Transaction States¶
draft ──▶ pending ──▶ sent ──┬──▶ partially_paid ──▶ paid
│ │
│ ▼
├──▶ overdue ──▶ paid
│
└──▶ cancelled
│
▼
voided
4.3 RPS States¶
created ──▶ pending ──▶ processing ──┬──▶ processed ──▶ (terminal)
▲ │
│ └──▶ failed ──┬──▶ pending (retry)
│ │
└─────────────────────────────────┘
└──▶ cancelled (terminal)
4.4 Recurrence States¶
active ──┬──▶ paused ──▶ active (resume)
│
├──▶ completed (all installments processed)
│
└──▶ cancelled (mid-plan cancellation)
5. Error Handling & Recovery¶
5.1 Transaction Generation Errors¶
| Error | Cause | Recovery |
|---|---|---|
| Missing line items | Billing instruction not applied to debtor | Flag for admin review; exclude debtor from batch |
| Amount mismatch | Pricing rule conflict | Log discrepancy; use manual override |
| Duplicate transaction | Retry after partial failure | Idempotency check on (debtor_id + billing_cycle_id + type) |
| ERP sync failure | Network/API error | Queue for retry; continue generation |
5.2 Payment Processing Errors¶
| Error | Cause | Recovery |
|---|---|---|
| Gateway timeout | eway/bank unavailable | Retry with exponential backoff |
| Card declined | Insufficient funds, expired card | Notify parent; schedule retry (configurable) |
| Invalid BSB/account | Incorrect bank details | Flag debtor; admin contacts parent |
| Duplicate payment | Re-processing already processed RPS | Idempotency check on RPS ID |
| Amount discrepancy | Partial payment received | Create partial payment record; update outstanding |
5.3 Data Integrity Checks¶
Run as scheduled job (daily):
| Check | Query | Alert if |
|---|---|---|
| Orphaned students | Students without debtors | Count > 0 |
| Unbalanced transactions | amount_paid + amount_outstanding ≠ total_amount | Any mismatch |
| Stale RPS | Pending RPS with past processing_date > 7 days | Count > 0 |
| Missing payments | Processed RPS without Payment Record | Count > 0 |
| ERP sync lag | Transactions not synced within 24h | Count > 0 |