Journal Entry Walkthrough
Journal Entry Walkthrough
Section titled β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"Sync vs. Async: What Decides the Mode?
Section titled βSync vs. Async: What Decides the Mode?β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.
Verify Manually After Clicking Submit
Section titled βVerify Manually After Clicking SubmitβConfirm the UI Response
Section titled βConfirm the UI Responseβ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.
Check the Journal Entry in Postgres
Section titled βCheck the Journal Entry in Postgresβpsql postgresql://postgres:<your_password>@localhost:5432/postgres-- Confirm status and transfer_idSELECT name, entry_number, status, docstatus, transfer_idFROM journalentryWHERE 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 = NULLCheck the GL Projection Rows
Section titled βCheck the GL Projection Rowsβ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_reversalFROM financialglentryWHERE voucher_no = '0017'; -- use your entry_numberThese rows are what General Ledger, P&L, and Balance Sheet reports query. They are a local projection of the authoritative state in ledger-core.
Check the Outbox Queue (Async Path Only)
Section titled βCheck the Outbox Queue (Async Path Only)βIf the entry went through the async path, an OutboxEntry row will be present:
SELECT id, operation, status, reference_id, retry_count, errorFROM outboxentryWHERE reference_doctype = 'JournalEntry'ORDER BY created_at DESCLIMIT 5;
-- Before relay: status = "Pending", reference_id = "0017"-- After relay: status = "Sent"Ensure the Background Worker Is Running
Section titled βEnsure the Background Worker Is RunningβThe relay_outbox job runs on the finance worker pool. Start it with:
uv run m dev --env-file monolith.env --enable-workerOnce running, it picks up pending outbox entries and processes them within seconds.
Architecture Summary
Section titled βArchitecture Summaryβ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_submithook), not a generic repository save. FinanceLedgerServiceis the single entry point to the ledger, backed byledger-coreadapters.- The Outbox pattern ensures GL posting survives transient ledger unavailability.
FinanceGLEntryrows are the local read-model for all financial reports.- Cancellation enqueues a
cancel_journal_entryoutbox operation that writes reversedFinanceGLEntryrows. - Budget utilization is tracked synchronously (local DB only) on both submit and cancel.
Quick Reference: Status States
Section titled βQuick Reference: Status Statesβ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 |