Note (2026-04-24): After this document was written, legal_entity was renamed to tenant and the old tenant was renamed to organization. Read references to these terms with the pre-rename meaning.

AR Module Design

Context

Orcha's first feature was Accounts Payable (AP) — ingesting, classifying, and matching incoming invoices. We're now adding Accounts Receivable (AR) as a parallel module, starting with the UI for creating and managing outgoing invoices.

AR will eventually have its own ingestion pipeline (external systems pushing/pulling data to create draft invoices), but this iteration focuses on the UI and data model foundation.

Decisions

Data Model

Document type rename: The document_type enum currently has invoice (implicitly incoming). Rename to incoming-invoice and add outgoing-invoice.

Migration steps:

1. Add incoming-invoice and outgoing-invoice enum values
2. UPDATE document SET type = 'incoming-invoice' WHERE type = 'invoice'
3. Make content_hash and file_path nullable (outgoing invoices start as structured data, not files)
4. Convert content_hash unique constraint to partial unique index excluding nulls
5. Add status column to document table for AR workflow: draft, sent, paid
6. Update all code referencing :invoice type to :incoming-invoice

Why same table: AR invoices will also have matching (to contracts), and the document table already holds multiple types (contracts, POs, GRNs). A separate table would need to mirror the same structure. The type enum already discriminates document types — an outgoing invoice is just another type.

Structured Data Schema Split

Three layers:

• schema.invoice.common — shared fields: invoice-number, invoice-date, total, subtotal, issuer, recipient, line-items, currency, discount, tax-rate-breakdowns, due-date, payment-terms, amount-due, notes, shipping, prepayments, installments
• schema.invoice.incoming — wraps common + pipeline outputs: confidence, fraud-flags, tax-issues, validation-results, service-category, and line item post-processing fields (debit-account, credit-account, accrual, cost-center, vat-validation, bu-code)
• schema.invoice.outgoing — wraps common + internal-notes (minimal for now, no speculative fields)

PDF Rendering

Protocol: PdfRenderer with render-to-pdf method taking an HTML string and options map, returning PDF bytes. Single implementation: OpenHtmlToPdfRenderer wrapping the existing PdfRendererBuilder pattern.

Shared across codebase: Extract from existing duplicated code in:

• workers.ap.acquisition.html (email/Excel → PDF)
• integrations.ap.cover_page (DATEV validation cover page)
• New AR preview endpoint

All three refactored to use the shared renderer.

Why OpenHTMLToPDF: Already in deps.edn, already used in two places, pure JVM (no infrastructure), fast enough for live preview (~50-100ms). Coded behind a protocol so the engine is replaceable if needed.

Template System

Multimethod dispatching on tenant, returning hiccup:

(defmulti render-invoice-template :tenant-id)

(defmethod render-invoice-template :default [invoice-data]
  [:div.invoice ...])

Custom templates = new defmethod per tenant, converting customer-provided HTML to hiccup as code. Hiccup → HTML string → OpenHTMLToPDF → PDF bytes.

No template engine (no Selmer), no S3 storage, no runtime loading, no template builder. Default template ships with Orcha.

Live PDF Preview

1. User edits form field
2. HTMX hx-post with throttle:300ms sends form data to server
3. Server coerces to outgoing invoice structured data
4. Multimethod renders tenant template as hiccup → HTML string
5. OpenHTMLToPDF converts to PDF bytes (~50-100ms)
6. Response streams PDF (Content-Type: application/pdf)
7. Client-side iframe refreshes with new PDF

Target round-trip: under 500ms.

UI Specification

Invoice Create/Edit Form

Layout: Split pane — form on the left, PDF preview on the right. Responsive: preview collapses or moves below on small screens.

Form fields:

Header:

• Recipient (client) — autocomplete/dropdown, required
• Invoice number — auto-generated, editable
• Invoice date — date picker, defaults to today
• Due date — date picker
• Currency — dropdown
• PO reference — text input

Line items table (editable rows):

• Type: product / section header / note
• Description — text input (required for product lines)
• Quantity — number input
• Unit price — number input
• Discount % — number input
• Tax rate % — number input
• Amount — calculated, readonly
• "Add line" / "Add section" / "Add note" buttons

Totals (calculated, readonly):

• Subtotal
• Discount (invoice-level, optional — editable)
• Tax breakdowns (grouped by rate)
• Total

Notes:

• Public notes (shown on invoice)
• Internal notes (not on invoice)
• Payment terms / conditions (text)

Issuer comes from tenant/legal entity config, not the form.

Overview/List Screen

Mirrors AP list structure.

Columns:

• Created date
• Legal entity (multi-LE tenants only)
• Invoice number
• Client (recipient name)
• Total + currency
• Due date
• Status badge (draft / sent / paid)

Filters:

• Status: All, Draft, Sent, Paid
• Date range
• Client (dropdown)
• Legal entity (multi-LE only)

Sorting: Default by created date descending. Clickable column headers.

Actions:

• "Create" button → create form
• Row click → edit form

Code Organization

New namespaces:

• com.getorcha.app.http.ar — list page, create/edit form, preview endpoint
• com.getorcha.schema.invoice.common — shared invoice fields
• com.getorcha.schema.invoice.incoming — incoming-specific (replaces current schema.invoice.structured-data)
• com.getorcha.schema.invoice.outgoing — outgoing-specific
• com.getorcha.pdf.renderer — PdfRenderer protocol + OpenHtmlToPdfRenderer

Modified namespaces:

• com.getorcha.schema.structured-data — update dispatch for incoming-invoice / outgoing-invoice
• All namespaces referencing document.type = :invoice → :incoming-invoice
• workers.ap.acquisition.html — refactor to use shared renderer
• integrations.ap.cover_page — refactor to use shared renderer

Not created this iteration:

• No workers/ar/ — no ingestion pipeline
• No integrations/ar/ — no export/send

Deliberately Excluded

• AR ingestion pipeline (external data sources → draft invoices)
• Export/send functionality
• Payment tracking beyond status field
• Template builder / template editor
• Custom fields, surcharges
• Partial payments / deposits
• Exchange rates / multi-currency conversion
• Bulk actions on list screen
• SSE / real-time updates on list screen
• UOM (unit of measure) system
• Fiscal positions
• Salesperson assignment
• Project linking