Documentation Index

Fetch the complete documentation index at: https://docs.encoreos.io/llms.txt

Use this file to discover all available pages before exploring further.

​

Enhancement: Recurring Invoicing & Collections - Integration Documentation

​

Integration Overview

​

Platform Foundation (PF) Integrations

​

PF-01 (Organizations & Sites)

• Type: Direct dependency
• Usage: organization_id on all tables for multi-tenant isolation
• Direction: FA-05 Enhancement → PF-01

​

PF-02 (RBAC)

• Type: Direct dependency
• Usage: Permission checks for AR operations using fa_has_recurring_invoice_access() and fa_is_org_admin() SECURITY DEFINER functions
• Direction: FA-05 Enhancement → PF-02

​

PF-10 (Notifications)

• Type: Platform Integration Layer via @/platform/notifications
• Usage: Invoice generation notifications, collection notices, overdue installment alerts
• Events consumed: None
• Events published:
  • recurring_invoice.generated → triggers email/in-app notification to customer
  • payment_plan.installment_due → triggers reminder notification
  • payment_plan.installment_overdue → triggers overdue alert
  • collection.workflow_started → triggers collection notice to customer
  • bad_debt.written_off → triggers internal notification to finance team

​

Forms & Workflow (FW) Integration

​

FW-03 (Workflow Engine)

• Type: Platform Integration Layer
• Usage: Payment plan approval, collection workflow automation, bad debt write-off approval

​

Payment Plan Approval

• Trigger Event: payment_plan.submitted_for_approval
• Payload: { payment_plan_id: UUID, customer_id: UUID, total_amount: DECIMAL, organization_id: UUID }
• Condition: Triggered when total_amount > payment_plan_approval_threshold (from fa_module_settings)
• Outcome: Workflow approval → payment plan status changes from ‘pending_approval’ to ‘approved’/‘active’

​

Collection Workflow

• Trigger Event: invoice.past_due_threshold
• Payload: { invoice_id: UUID, customer_id: UUID, days_past_due: INTEGER, balance_due: DECIMAL, organization_id: UUID }
• Default Template: Notice (Day 1) → Follow-up Notice (Day 15) → Final Notice (Day 30) → Write-off Review (Day 60)
• Outcome: Automated escalation through collection steps with PF-10 notifications at each stage

​

Bad Debt Write-Off Approval

• Trigger Event: bad_debt.write_off_requested
• Payload: { invoice_id: UUID, customer_id: UUID, write_off_amount: DECIMAL, reason: TEXT, organization_id: UUID }
• Outcome: Approval → creates FA-02 journal entry, updates invoice status, creates bad debt reserve record

​

FA-02 (General Ledger) Integration

• Type: Direct data dependency (same core)
• Usage: Bad debt write-off creates journal entries
• Direction: FA-05 Enhancement → FA-02
• Tables Referenced: fa_journal_entries (FK from fa_bad_debt_reserves.journal_entry_id)

​

Edge Function Contracts

​

fa-generate-recurring-invoices

• Schedule: Hourly (0 * * * *)
• Auth: Service-role key (cron-triggered)
• Input: None (queries fa_recurring_invoices where status = 'active' and next_generation_date <= now())
• Output: Creates fa_invoices records, publishes recurring_invoice.generated events
• Error Handling: Logs errors per template; does not advance next_generation_date on failure

​

fa-check-collection-thresholds

• Schedule: Daily at midnight (0 0 * * *)
• Auth: Service-role key (cron-triggered)
• Input: None (queries past-due invoices against collection_threshold_days setting)
• Output: Creates FW-03 workflow instances, publishes invoice.past_due_threshold events

​

fa-check-installment-due-dates

• Schedule: Daily at 6 AM (0 6 * * *)
• Auth: Service-role key (cron-triggered)
• Input: None (queries fa_payment_plan_installments for upcoming/overdue due dates)
• Output: Publishes payment_plan.installment_due and payment_plan.installment_overdue events

​

Security & Tenant Isolation

• All integrations include organization_id in event payloads
• Edge functions filter by organization_id for all queries
• RLS policies enforce tenant isolation on all FA-05 Enhancement tables
• SECURITY DEFINER functions (fa_has_recurring_invoice_access, fa_is_org_admin) used for RLS helpers