The Accounting Bridge

​

Why a bridge

• Idempotency & traceability — every product transaction maps to exactly one accounting_source_links row (entities/accounting-source-link.entity.ts), giving drill-through, reconciliation, replay, and dedupe.
• Routing — products supply a businessId, not a book; the bridge resolves business → book → workspaceId and refuses to guess when ambiguous.
• Account abstraction — products name accounts by stable systemCode (cash, sales_revenue, staff_advances); the bridge resolves them to the book’s actual chart UUIDs.
• Decoupling — a product never imports a GL service, so the chart, posting pipeline, and period rules can evolve behind a stable intent contract.

​

The contract surface

​

HTTP — AccountingBridgeController (controllers/accounting-bridge.controller.ts)

​

In-process — AccountingBridgeService (services/accounting-bridge.service.ts)

​

The payload — JournalIntentPayload (interfaces/bridge.interfaces.ts)

interface JournalIntentPayload {
  tenantId: string;
  businessId: string;
  targetBookId?: string;        // multi-book products (Tax/IFRS/Management)
  productKey: string;           // e.g. 'payroll', 'sacco', 'fixed-assets'
  intentType: string;          // e.g. 'payroll.run.posted' → JournalSourceType
  sourceType: string;          // your record's type, e.g. 'payroll_run'
  sourceId: string;            // your record's id (idempotency coordinate)
  occurredAt: Date;
  idempotencyKey: string;
  actorUserId: string;
  memo?: string;
  dimensions?: Record<string,string>;  // entry-level, e.g. cost_center_id
  lines: JournalIntentLine[];  // keyed by accountSystemCode (or direct accountId)
}

Cost center is entry-level, not per-line (gl3). A JournalIntentLine has no cost center; it lives in dimensions.cost_center_id and is projected onto every line. A connector needing different cost centers per line must split into per-cost-center intents.

​

How publishJournalIntent works

1. Fast-path idempotency — findSourceLink(...); a POSTED link returns immediately with created: false.
2. Routing — routingService.resolve({tenantId, businessId, bookId: targetBookId}).
3. Claim the source link before posting — claimJournalSourceLink. The partial unique index IDX_acctsrc_product_source over (tenant_id, product_key, source_type, source_id) is the ordering authority: exactly one of N concurrent identical intents wins the insert; losers re-read. A pre-existing PENDING/FAILED link is claimed atomically (tryAtomicClaimExistingLink — a single UPDATE ... WHERE posting_status IN (PENDING,FAILED)) so two callers can’t both adopt it and leave a stale FAILED next to a live POSTED journal.
4. Resolve lines — profileResolver.resolveJournalLines; fewer than 2 resolved lines → BadRequestException.
5. Create + post the journal via JournalService. A uq_journal_entries_source violation (a second caller slipped through the narrow window) is recovered by journalRepository.findBySource rather than erroring.
6. Finalize — stamp the source link POSTED with the journalEntryId. Any throw stamps it FAILED with lastError.

​

intentType → JournalSourceType mapping

​

Staff money — the resolver + provisioning pair

​

StaffPostingBookResolver (services/staff-posting-book-resolver.service.ts)

• resolveBook(tenantId, employeeId, businessId) — validates the employee has an active EmploymentContract (workflowState = ACTIVE and docstatus = 1 — a draft Active contract must not authorize a route) in that business, then delegates to AccountingRoutingService.resolve. No active contract → STAFF_NO_ACTIVE_CONTRACT.
• resolveBusinessIdForEmployee(tenantId, employeeId) — when the business is unknown, derives it from the employee’s active contracts: exactly one → that business; none → STAFF_NO_ACTIVE_CONTRACT; multiple → STAFF_MULTI_BUSINESS (the caller must disambiguate — the resolver never guesses).

​

EmployeeContactProvisioningService (services/employee-contact-provisioning.service.ts)

• ensureForBusiness(tenantId, employeeId, bookId) returns the contact id, creating it on first use (Contact.workspaceId == bookId, type = ContactType.EMPLOYEE, employeeId FK). Safe under concurrency: a racing create that loses the partial-unique index (23505) re-reads the winner.

​

Worked example — an external module posts a payroll run

// inside the payroll module (pseudocode)
const businessId = await staffPostingBookResolver
  .resolveBusinessIdForEmployee(tenantId, anchorEmployeeId);          // or carried on the run
const { bookId } = await staffPostingBookResolver
  .resolveBook(tenantId, anchorEmployeeId, businessId);
const employeeContactId = await employeeContactProvisioning
  .ensureForBusiness(tenantId, employeeId, bookId);

await accountingBridge.publishJournalIntent({
  tenantId,
  businessId,
  productKey: 'payroll',
  intentType: 'payroll.run.posted',          // → JournalSourceType.PAYROLL
  sourceType: 'payroll_run',
  sourceId: run.id,                            // idempotency coordinate
  occurredAt: run.postingDate,
  idempotencyKey: `payroll:${run.id}`,
  actorUserId: userId,
  dimensions: { cost_center_id: run.costCenterId },
  lines: [
    { accountSystemCode: 'salary_expense',  debit: gross,  credit: 0 },
    { accountSystemCode: 'paye_payable',    debit: 0,      credit: paye },
    { accountSystemCode: 'salary_payable',  debit: 0,      credit: net,
      contactId: employeeContactId },
  ],
});

1. Idempotency check on (payroll, payroll_run, run.id) — a re-fire of the same run returns the prior result, no duplicate JE.
2. Routing resolves businessId → bookId → workspaceId.
3. resolveJournalLines maps salary_expense/paye_payable/salary_payable to the book’s chart UUIDs (a missing control account → JOURNAL_ACCOUNT_UNRESOLVED).
4. JournalService.create + post runs the full posting engine (balance, period/frozen guards, ledger write) — see posting-engine.md.
5. The source link is stamped POSTED with the journalEntryId; the connector gets back { created: true, accountingDocumentId, accountingBookId } and can store the JE id for drill-through.

await accountingBridge.reverseBySource({
  tenantId, businessId,
  productKey: 'payroll', sourceType: 'payroll_run', sourceId: run.id,
  actorUserId: userId,
});

​

Extension points

• Onboard a new product → call publishJournalIntent (sync) or AccountingOutboxWriterService.writeJournalIntent (async). Always pass a stable (productKey, sourceType, sourceId) triple — it is your idempotency and drill-through key.
• Add an intentType → extend mapIntentToSourceType; add the enum value to JournalSourceType (enums/journal-source-type.enum.ts) when a new bucket is warranted, so the source-type reconciliation views stay accurate.
• New staff money path → resolve the book through StaffPostingBookResolver and the counterparty through EmployeeContactProvisioningService; never invent book selection in the connector.
• Support a new document type → wire BILL/CREDIT_NOTE in publishDocumentIntent and mapDocumentType (currently only INVOICE).