Skip to content

Journal Entry Walkthrough

What Actually Happens When You Click β€œSubmit”

Section titled β€œWhat Actually Happens When You Click β€œSubmit””

Journal entries do not go through a generic repo.save() call. Submission is handled by a task-based RPC β€” a dedicated on_submit hook on JournalEntryController. Here is the precise chain, from browser click to committed GL entry:

[Browser]
└─ POST /api/v1/workflow/JournalEntry/{uuid}/transition { action: "Submit" }
β”‚
[JournalEntryController.on_submit()]
β”œβ”€ Validates: total_debit == total_credit, total_debit > 0, β‰₯ 2 legs
β”œβ”€ Validates: posting date falls within an open AccountingPeriod
β”œβ”€ Calls LedgerModeResolver.resolve(doc) β†’ "sync" | "async"
β”‚
β”œβ”€β”€β”€ [sync mode] ──────────────────────────────────────────────
β”‚ β”œβ”€ Calls FinanceLedgerService.submit_compound_entry(...)
β”‚ β”‚ └─ ledger-core LedgerPort.transfer(TransferCommand)
β”‚ β”‚ └─ TigerBeetleLedger or SqlAlchemyLedger (from settings)
β”‚ β”œβ”€ Sets doc.transfer_id = <ledger transfer UUID>
β”‚ β”œβ”€ Sets doc.status = "Submitted"
β”‚ └─ Writes FinanceGLEntry projection rows (local DB, for reports)
β”‚
└─── [async mode] ─────────────────────────────────────────────
β”œβ”€ Builds OutboxEntry { operation="post_journal_entry", payload_json=... }
β”œβ”€ await self.db.insert(entry) ← written to outboxentry table
└─ Sets doc.status = "Pending GL"
β”‚
[relay_outbox job β€” scheduled background worker]
β”œβ”€ Claims pending OutboxEntry rows (FOR UPDATE SKIP LOCKED)
β”œβ”€ Calls FinanceLedgerService.submit_compound_entry(...)
β”‚ └─ Same ledger-core path as sync mode
β”œβ”€ On success:
β”‚ β”œβ”€ OutboxEntry.status = "Sent"
β”‚ β”œβ”€ JournalEntry.transfer_id = <ledger transfer UUID>
β”‚ β”œβ”€ JournalEntry.status = "Submitted"
β”‚ └─ Bulk-inserts FinanceGLEntry projection rows
└─ On transient failure: increments retry_count (exponential backoff)
On exhausted retries: OutboxEntry.status = "Dead"

LedgerModeResolver is a DI-injected protocol. The default implementation (PaymentTermsResolver) applies these rules:

Condition Mode
payment_terms is "Immediate" / "Cash" / "Advance" sync
party_type is "Cash" or "Bank" sync
payment_terms indicates a credit period async
No payment terms (plain journal entry) sync (default)

In practice, plain journal entries always take the sync path.


After clicking Submit, the controller returns:

{
"success": true,
"old_state": "Draft",
"new_state": "Submitted",
"action": "Submit",
"message": "Transitioned from Draft to Submitted"
}

For a plain journal entry (sync path), status should immediately show β€œSubmitted” and transfer_id should be populated.


Terminal window
psql postgresql://postgres:<your_password>@localhost:5432/postgres
-- Confirm status and transfer_id
SELECT name, entry_number, status, docstatus, transfer_id
FROM journalentry
WHERE name = 'JOUR-53CBEC53';
-- Sync path expected:
-- status = "Submitted"
-- docstatus = "1"
-- transfer_id = "compound_entry_xxxxxxxx"
-- Async path expected (before relay runs):
-- status = "Pending GL"
-- transfer_id = NULL

After submission (sync) or after the relay worker runs (async), local FinanceGLEntry rows are written for every leg:

SELECT voucher_type, voucher_no, account, debit, credit, fiscal_year, is_reversal
FROM financialglentry
WHERE voucher_no = '0017'; -- use your entry_number

These rows are what General Ledger, P&L, and Balance Sheet reports query. They are a local projection of the authoritative state in ledger-core.


If the entry went through the async path, an OutboxEntry row will be present:

SELECT id, operation, status, reference_id, retry_count, error
FROM outboxentry
WHERE reference_doctype = 'JournalEntry'
ORDER BY created_at DESC
LIMIT 5;
-- Before relay: status = "Pending", reference_id = "0017"
-- After relay: status = "Sent"

The relay_outbox job runs on the finance worker pool. Start it with:

Terminal window
uv run m dev --env-file monolith.env --enable-worker

Once running, it picks up pending outbox entries and processes them within seconds.


JournalEntryController.on_submit()
β”‚
β”œβ”€β”€ [sync] FinanceLedgerService.submit_compound_entry()
β”‚ β”‚
β”‚ ledger-core LedgerPort
β”‚ β”‚
β”‚ TigerBeetleLedger OR SqlAlchemyLedger
β”‚ β”‚
β”‚ TigerBeetle / PostgreSQL (single DB)
β”‚
└── [async] OutboxEntry (outboxentry table)
β”‚
relay_outbox job
β”‚
FinanceLedgerService (same path as sync)

Key points:

  • Submission is a task-based RPC (on_submit hook), not a generic repository save.
  • FinanceLedgerService is the single entry point to the ledger, backed by ledger-core adapters.
  • The Outbox pattern ensures GL posting survives transient ledger unavailability.
  • FinanceGLEntry rows are the local read-model for all financial reports.
  • Cancellation enqueues a cancel_journal_entry outbox operation that writes reversed FinanceGLEntry rows.
  • Budget utilization is tracked synchronously (local DB only) on both submit and cancel.

docstatus status What it means
0 Draft Being drafted, editable
1 Pending GL Submitted (async path), waiting for relay_outbox
1 Submitted Ledger confirmed; transfer_id populated
1 GL Rejected Ledger returned a permanent business rejection (4xx)
2 Cancelled Reversed; cancellation relay complete