Accounting Posting Engine

​

The two write paths and one engine

1. Synchronous bridge call — a product posts a journal intent and waits for the result. AccountingBridgeService.publishJournalIntent (services/accounting-bridge.service.ts) resolves routing + accounts, calls JournalService.create then JournalService.post, which invokes the posting engine. Covered in accounting-bridge.md.
2. Asynchronous outbox — a product writes an intent to a durable outbox row and returns immediately. A cron drains the outbox and replays each intent through the same bridge. This is the path described below as the “intent → outbox → ledger pipeline”.

​

Stage 1 — the outbox writer

• Dedupe key is deterministic: `${productKey}:${sourceType}:${sourceId}` (generateDedupeKey). Before inserting it calls findByDedupeKey(tenantId, dedupeKey); on a hit it returns the existing outbox id rather than enqueuing a duplicate. The entity enforces this at the DB level too — @Index(['tenantId','dedupeKey'], { unique: true }) (entities/accounting-intent-outbox.entity.ts).
• bookId is intentionally left null — “resolved at processing time by the bridge from businessId”. The column is nullable for exactly this reason; it was once NOT NULL and 500’d every write.
• The row starts status = PENDING, attemptCount = 0, availableAt = now().

​

Stage 2 — the intent processor (drain loop)

@Cron(EVERY_30_SECONDS) handleOutboxCron()
  → processOutbox()
      pending = findPendingItems(BATCH_SIZE=20)   // PENDING && availableAt<=now, ORDER BY dateCreated ASC
      for each chunk of CONCURRENCY=5:
        Promise.allSettled(chunk.map(processItem))

1. Optimistic lock — lockForProcessing(id, tenantId) does UPDATE ... SET status=PROCESSING WHERE id=? AND status=PENDING. If affected === 0 another worker already took it → return false (skipped). This is what makes the loop safe to run on multiple instances.
2. Dispatch — document intents (payload has a document property) go to bridgeService.publishDocumentIntent; everything else to bridgeService.publishJournalIntent. Dates stored as ISO strings are revived (reconstructJournalPayload / reconstructDocumentPayload).
3. On success — markCompleted(id, tenantId) (status COMPLETED, processedAt = now).
4. On failure — retry-or-dead-letter (next section).

​

Retries, backoff, and the dead-letter queue

• If nextAttempt >= MAX_RETRIES → markDeadLetter(...) (terminal DEAD_LETTER, no further retries).
• Otherwise → markFailed(id, tenantId, error, nextAvailableAt) which resets the row to PENDING, sets a future availableAt, and increments attempt_count atomically ("attempt_count" + 1).

Dead-letter is the diagnostic surface. A recurring DEAD_LETTER for a money path usually means a configuration gap (e.g. a missing system account in the book’s chart), not a code bug — the engine fails loud rather than posting a half-entry.

​

Stage 3 — the bridge and account resolution

1. Source-link idempotency — looks up the accounting_source_links row for (tenant, productKey, sourceType, sourceId). A POSTED link short-circuits with created: false.
2. Routing — AccountingRoutingService.resolve({tenantId, businessId, bookId?}) maps the business to a concrete bookId + compatibility workspaceId. It honours an explicit targetBookId (multi-book products like fixed-assets), else the business defaultBookId, else the single active book — and throws BOOK_ROUTING_AMBIGUOUS rather than guessing among several.
3. Profile / account resolution — PostingProfileResolver.resolveJournalLines converts intent lines keyed by accountSystemCode into journal lines keyed by account UUID (next section).
4. Creates + posts the journal via JournalService, then stamps the source link POSTED.

​

Posting profiles and system-code → account routing

• resolveProfile(tenantId, bookId, transactionType) loads an AccountingPostingProfile (entities/accounting-posting-profile.entity.ts) — a (book, productKey, transactionType)-keyed row whose rulesJson follows PostingProfileRule (interfaces/bridge.interfaces.ts): { lines: [{ role: 'debit'|'credit', accountSystemCode }], autoPost?, journalSourceType? }. Resolution prefers the highest version of a book-specific active profile.
• resolveJournalLines(intentLines, workspaceId, tenantId) is the path actually used by the bridge today. For each line:
  • a direct accountId wins verbatim (fixed-assets resolves accounts upstream);
  • otherwise accountSystemCode is looked up in the book’s chart (AccountsRepository.findBySystemCodes), falling back to a built-in DEFAULT_ACCOUNTS map (constants/default-accounts);
  • fail-loud (gl2): a value-bearing line whose account can’t resolve throws BadRequestException with code: 'JOURNAL_ACCOUNT_UNRESOLVED' and the offending system codes — a missing control account surfaces as a precise error rather than a confusing “UNBALANCED” / “fewer than 2 lines”. Zero-value placeholder lines are silently dropped.

​

Stage 4 — the posting engine

​

Idempotency key (engine-level, distinct from source links)

INSERT INTO posting_idempotency_keys (tenantId, journalEntryId, idempotencyKey)
// unique index (tenantId, journalEntryId, idempotencyKey)
// duplicate-key error → log + return (skip the write) — no TOCTOU window

​

Validate → guard → merge → round-off

1. loadAccountsCached(entry) — loads referenced accounts (5s cache), hard-fails on any account outside the tenant/workspace.
2. PostingValidatorService.validate(lines, accounts) (posting/posting-validator.service.ts) collects PostingIssues: UNBALANCED (|ΣDr − ΣCr| > 0.005), MISSING_REQUIRED_FIELD (both debit and credit set), ACCOUNT_NOT_POSTABLE (group / non-postable), ACCOUNT_DISABLED.
3. FrozenAccountGuardService.check(...) and PeriodLockGuardService.check(...) — the latter returns ok | override | blocked, emitting PERIOD_LOCKED / PERIOD_CLOSED issues (overridable via context.overrides.periodLock).
4. PostingRowMergerService.merge(rows) (opt-in via context.mergeRows) nets duplicate (accountId, contact, category, costCenter, book, dims) rows and drops rows that net to zero (posting/posting-row-merger.service.ts).
5. RoundOffCalculatorService.calculate(...) (opt-in via context.applyRoundOff) appends a single balancing round-off row against the SYS_ROUND_OFF system account (5-minute cache).

​

The ledger write (ordering & atomicity)

1. Existence guard — count ledger rows for this journalEntryId; if any exist, throw Ledger entries already exist for posted journal entry (replay protection at the GL layer).
2. Write rows — if the caller supplied pre-merged rowDrafts, they’re written verbatim (toLedgerEntryFromDraft); otherwise one ledger row is synthesized per journal line (toLedgerEntry). Per-line costCenterId is folded into dimensions.cost_center_id so the Cost-Center P&L sees tagged rows.
3. WHT balance deltas — when whtBalanceDeltas is present, a raw INSERT ... ON CONFLICT DO UPDATE upserts withholding_balances inside the same transaction, so a WHT failure rolls back the GL insert.

​

Reversals

​

Bulk posting

• Max 1000 intents per batch.
• Each intent is independent — a failure on intent N does not roll back 0..N-1. (An outer transaction would be a lie because the bridge opens its own connection internally.)
• In-batch dedupe — intents sharing (tenantId, productKey, sourceType, sourceId) collapse: the first is published, later ones are reported status='skipped', reason='duplicate_in_batch'.
• Bridge-level idempotency still applies — an intent whose source already has a POSTED link comes back created:false → reported reason='already_posted'.
• Returns per-row {index, status: posted|skipped|failed, reason?, result?, error?} plus totals.

​

Ordering & idempotency guarantees — summary

​

Extension points

• Add a posting source → see accounting-bridge.md: publish a JournalIntentPayload, then add the intentType → JournalSourceType mapping in accounting-bridge.service.ts mapIntentToSourceType (an unmapped intent posts under INTEGRATION and logs a warning — a reconciliation blind spot, never a blocked posting).
• Add an account-mapping profile → insert an AccountingPostingProfile (versioned, (book, productKey, transactionType)).
• Add a posting-time guard/validation → add a service under posting/ and call it from validateAndPrepareRows so it runs for sync and async paths.
• Add a new dimension on GL rows → extend GLRowDraft (posting/posting-row-merger.service.ts) and the toLedgerEntry* mappers, and include it in PostingRowMergerService.keyOf if it should affect netting.