integreat/docs/testing/behaviors/ledger.md

Ledger Behaviors

Overview

The Ledger module is the core accounting interface of Integreat. It provides server-side rendered (HTMX) pages for viewing journal entries, creating manual journal entries, and generating financial reports (Profit & Loss, Balance Sheet, Cash Flows). All ledger pages are permission-gated and client-scoped.

Routes & Pages

Route	Method	Handler	Description
/ledger	GET	::all-page	Main ledger entries list (internal)
/ledger/external-new	GET	::external-page	External ledger entries list
/ledger/new	GET	::new	Modal form for new journal entry
/ledger/new	POST	::new-submit	Submit new journal entry
/ledger/new/location-select	GET	::location-select	Location dropdown for line item
/ledger/new/account-typeahead	GET	::account-typeahead	Account search for line item
/ledger/new/line-item	GET	::new-line-item	Add new line item row
/ledger/external-import-new	GET	::external-import-page	External TSV import page
/ledger/external-import-new/parse	POST	::external-import-parse	Parse clipboard TSV data
/ledger/external-import-new/import	POST	::external-import-import	Import validated entries
/ledger/investigate	GET	::investigate	Investigation modal for report drill-down
/ledger/investigate/results	GET	::investigate-results	Investigation results table
/ledger/table	GET	::table	HTMX table fragment for ledger entries
/ledger/csv	GET	::csv	CSV export of ledger entries
/ledger/bank-account-filter	GET	::bank-account-filter	Bank account filter widget
/ledger/reports/profit-and-loss	GET	::profit-and-loss	P&L report page
/ledger/reports/profit-and-loss/run	PUT	::run-profit-and-loss	Run P&L report
/ledger/reports/profit-and-loss/export	POST	::export-profit-and-loss	Export P&L to PDF
/ledger/reports/balance-sheet	GET	::balance-sheet	Balance sheet page
/ledger/reports/balance-sheet/run	GET	::run-balance-sheet	Run balance sheet
/ledger/reports/balance-sheet/export	POST	::export-balance-sheet	Export balance sheet to PDF
/ledger/reports/cash-flows	GET	::cash-flows	Cash flows page
/ledger/reports/cash-flows/run	PUT	::run-cash-flows	Run cash flows report
/ledger/reports/cash-flows/export	POST	::export-cash-flows	Export cash flows to PDF

Behaviors by Page

Ledger Entries List

Page load

• Displays a paginated, sortable data grid of journal entries
• Shows client selection sidebar if user has access to multiple clients
• Title reflects status filter: e.g. "Unpaid Register" or "Paid Register"
• Includes an "Add journal entry" button (hidden on external ledger page)

Columns displayed

• Client (hidden if only 1 client with 1 location)
• Vendor (falls back to alternate-description if no vendor)
• Source (hidden on internal ledger)
• External ID (hidden on internal ledger, truncated to max-width)
• Date
• Amount (formatted as currency)
• Debit lines (account + location + amount)
• Credit lines (account + location + amount)
• Links dropdown (links to original invoice, source file, transaction, or memo)

Row actions

• Void button for unpaid invoices (requires :delete :invoice permission)
• Edit button for unpaid/paid invoices (requires :edit :invoice permission)
• Unvoid button for voided invoices (requires :edit :invoice permission)
• Trash icon with confirmation for delete operations

Sorting

• Available sorts: Client, Vendor, Source, External ID, Date, Amount, Account
• Default sort: Date ascending
• Sorting by Vendor or Source groups rows with break headers

Filtering (left sidebar)

• Vendor typeahead search
• Account typeahead search
• Bank account radio filter (refreshes on client change)
• Date range picker
• Invoice number text search
• Account code range (gte/lte inputs)
• Amount range (gte/lte inputs)
• "Show unbalanced" checkbox (filters to entries where debits ≠ credits)
• Exact match ID pill (clears on click)

Pagination

• Default 25 entries per page
• Configurable per-page
• Pagination controls at bottom

CSV Export

• Exports all matching entries with line-item-level rows
• Columns: ID, Client, Vendor, Source, External ID, Date, Amount, Account, Debit, Credit

New Journal Entry

Modal form

• Opens as modal dialog (750px wide)
• Client typeahead (pre-filled if client already selected on parent page)
• Date input (default today, format MM/DD/YYYY)
• Vendor typeahead (disabled if editing existing entry)
• Total amount input (must be ≥ $0.01)
• Memo text input (optional)
• Line items grid with columns: Account, Location, Debit, Credit

Line item behaviors

• Account typeahead searches accounts scoped to selected client
• Location dropdown updates based on selected account's required location
• If account has a fixed location, dropdown is locked to that location
• If account has no location restriction, shows client's locations
• New line item rows added via HTMX request
• Line items can be removed with X button

Validation

• Client is required
• Date is required and must be valid
• Vendor is required
• Amount must be ≥ $0.01
• Each line item must have an allowed account
• Each line item must have a location belonging to the account
• Debits must sum to total amount
• Credits must sum to total amount
• Debits and credits must each equal the journal entry amount

On save

• Generates external ID: manual-<uuid>
• Updates client's ledger-last-change timestamp
• On POST: prepends new row to table, triggers modal close
• On PUT: replaces existing row in table, triggers modal close

External Import

Clipboard paste

• User clicks "Load from clipboard" button
• Reads TSV data from browser clipboard
• Parses tab-separated values with columns: Id, Client, Source, Vendor, Date, Account Code, Location, Debit, Credit

Parse validation

• Validates all rows have required fields
• Dates must be parseable
• Account codes must be numeric or bank account strings
• Locations must be 1-2 characters
• Debits/Credits must be valid money amounts

Import validation

• Client code must exist
• Vendor must exist (creates hidden vendor if missing)
• Client must not be locked for the entry date
• Debits and credits must balance per entry
• Entry cannot total $0.00 (warning)
• Location must belong to client
• Account code must exist
• Bank account code must belong to client
• Account location requirements must be satisfied

Import results

• Successful entries are imported
• Entries with warnings are ignored (removed if previously existed)
• Entries with errors block import and show error counts
• Retracts existing entries by external ID before importing
• Indexes imported entries in Solr asynchronously

P&L Report

Form

• Customer multi-select typeahead (max 20, defaults to first 5 if "all")
• Periods dropdown (default: year-to-date)
• "Column per location" toggle
• "Include deltas" toggle
• Run button (HTMX PUT)
• Export PDF button

Report generation

• Computes running balances before generating
• Queries detailed account snapshots for each client/period end date
• Amounts calculated as: debits - credits for assets/dividends/expenses, credits - debits for others
• Groups data by client, location, and period

Report output

• Summary table: Sales, COGS, Payroll, Gross Profits, Overhead, Net Income
• Detail table: Account-level breakdown within each category
• Percent of sales calculated for each row
• Deltas shown between periods if enabled
• Column-per-location mode shows each location as separate columns

Warnings

• Warns if >20 clients selected (truncates to 20)
• Warns about unresolved ledger entries (missing numeric codes)
• Shows sample links to admin history for invalid entries (if user has :view :history permission)

PDF Export

• Generates PDF with Calibri Light font, 6pt
• Uploads to S3 at reports/profit-and-loss/<uuid>/<name>.pdf
• Persists report record in Datomic
• Returns modal with download link

Balance Sheet

Form

• Customer multi-select typeahead (max 20, defaults to first 5 if "all")
• Date dropdown (single date, default today)
• "Include deltas" toggle
• Run button (HTMX GET)
• Export PDF button

Report generation

• Computes running balances before generating
• Queries account snapshot as of each selected date
• Groups by account categories: Assets, Liabilities, Owner's Equity
• Includes Retained Earnings (net income across all P&L categories)

Report output

• Assets section with account detail and subtotal
• Liabilities section with account detail and subtotal
• Owner's Equity section with account detail and subtotal
• Retained Earnings line
• Delta columns between periods if enabled and multiple dates selected

Warnings

• Warns if >20 clients selected
• Warns about unresolved ledger entries

PDF Export

• Generates PDF, uploads to S3 at reports/balance-sheet/<uuid>/<name>.pdf
• Persists report record in Datomic

Cash Flows

Form

• Customer multi-select typeahead (max 20, defaults to first 5 if "all")
• Periods dropdown (default: year-to-date)
• Run button (HTMX PUT)
• Export PDF button

Report generation

• Queries account snapshot as of period end + 1 day
• Groups accounts into: Operating Activities, Investment Activities, Financing Activities, Cash
• Calculates cash flow effect: add or subtract based on account code ranges

Report output

• Net Income starting point
• Operating Activities detail (increases, decreases, +/- in cash)
• Investment Activities detail
• Financing Activities detail
• Change in Cash and Cash Equivalents total
• Bank Accounts / Cash detail

Warnings

• Warns if >20 clients selected
• Warns about unresolved ledger entries

PDF Export

• Generates PDF, uploads to S3 at reports/cash-flows/<uuid>/<name>.pdf
• Persists report record in Datomic

Investigation

Modal behavior

• Opens as modal dialog from report table cell clicks
• Shows ledger entries filtered by the clicked cell's filters (account code range, client, location, date range)
• Displays raw table without checkboxes
• Max height 600px with scrollable content

Table behavior

• Uses same query schema as main ledger list
• Supports sorting and pagination
• Does not push URL state

Cross-Cutting Behaviors

Report generation

• All reports call upsert-running-balance before querying to ensure cached balances are current
• Reports use detailed-account-snapshot Datomic query for raw data
• Account lookups built per-client via build-account-lookup
• Reports skip entries without numeric codes (unassigned accounts) and warn

Export

• All three reports support PDF export via clj-pdf
• PDFs use Calibri Light 6pt font on letter size
• Uploaded to S3 data bucket with UUID-based key
• Report metadata persisted to Datomic (:report/name, :report/client, :report/key, :report/url, :report/creator, :report/created)
• Export returns modal with S3 download link

Filtering and sorting

• Ledger list filters applied via HTMX on change (500ms debounce) or keyup (1000ms debounce for hot filters)
• Bank account filter refreshes when client selection changes
• Sorting supports multiple sort keys with ascending/descending
• Default sort is date ascending
• Exact match ID filter bypasses all other filters

Permissions

• All ledger pages require authenticated user
• Main ledger: :read :ledger
• New/Edit journal entry: :edit :ledger
• External import: :import :ledger + admin assertion
• P&L report: :read :profit-and-loss
• Balance sheet: :read :balance-sheet
• Cash flows: :read :cash-flows
• Users can only see clients they have permission for (assert-can-see-client)
• Invoice void/edit/unvoid actions require respective invoice permissions

Edge Cases

Empty states

• No entries: empty table with pagination showing 0 results
• No matching filters: empty table, filter pills remain
• Report with no data: empty report form, no table rendered

Data locking

• Journal entries cannot be created for dates on or before client's locked-until date
• External import rejects entries for locked dates

Unbalanced entries

• "Show unbalanced" filter computes debit/credit sums per entry and filters to mismatches
• Unbalanced entries are still displayed in normal view

Account location mismatches

• Account with fixed location rejects other locations
• Account without location restriction rejects "A" (all) location
• Validation occurs on both frontend (location select) and backend (schema)

Multi-client reports

• Capped at 20 clients for performance
• "All" clients defaults to first 5 for reports
• Report names include all selected client names

Running balance cache

• refresh-running-balance-cache recomputes balances for dirty line items
• Changing a ledger entry marks its line items and subsequent entries as dirty
• Non-dirty entries are not recomputed

Test Data Requirements

Clients

• At least 2 clients with different locations
• Client with locked-until date in the past

Accounts

• Asset accounts (11000-11999)
• Liability accounts (20000-28999)
• Equity accounts (30000-39999)
• Revenue accounts (40000-49999)
• Expense accounts (50000-98999)
• Accounts with fixed locations
• Accounts without location restrictions

Vendors

• Existing vendors
• Hidden vendors (auto-created on import)

Journal entries

• Entries with debits = credits (balanced)
• Entries with debits ≠ credits (unbalanced)
• Entries with multiple line items
• Entries linked to invoices
• Entries with external IDs
• Entries across multiple dates and locations

Bank accounts

• Bank accounts linked to clients

Dependencies

• auto-ap.ssr.ledger.common - Shared grid page config, query schema, filtering
• auto-ap.ledger.reports - Report aggregation and formatting logic
• auto-ap.ledger - Running balance cache, account lookups
• auto-ap.datomic.accounts - Account querying and clientization
• auto-ap.permissions - Permission checks and middleware
• auto-ap.ssr.grid-page-helper - Generic data grid behaviors
• auto-ap.ssr.components - UI components (typeahead, date inputs, buttons)
• auto-ap.ssr.form-cursor - Form state management
• clj-pdf - PDF generation
• amazonica.aws.s3 - S3 upload for exports
• datomic.api - Database queries and transactions