Document Numbering Internals

How the accounting service allocates human-readable document numbers (invoice numbers, bill numbers, journal-entry numbers, …) per business, gap-free and collision-free under concurrency. Audience: engineers adding a new numbered document type or debugging a duplicate / out-of-sequence number.

Where it lives

File	Role
`src/accounting/services/document-sequence.service.ts`	The allocator: `nextValue` / `nextFormattedNumber`.
`src/accounting/entities/document-sequence.entity.ts`	TypeORM entity `DocumentSequence` → table `accounting_document_sequences`.
`src/accounting/migrations/1744000000000-AddAccountingSequencesAndLedgerImmutability.ts`	Creates the table, unique constraint and index.

DocumentSequenceService is registered in accounting.module.ts and injected into the repositories/services that mint numbers (see Call sites).

The storage model

One row per (tenant_id, workspace_id, sequence_key) tuple holds the last value handed out for that series. workspace_id here is the accounting book id (see the repo-wide “Workspace ID duality” note), so every book gets its own independent counter.

CREATE TABLE "accounting_document_sequences" (
  "id"            uuid NOT NULL DEFAULT uuid_generate_v4(),
  "tenant_id"     uuid NOT NULL,
  "workspace_id"  uuid NOT NULL,
  "sequence_key"  character varying(100) NOT NULL,
  "current_value" bigint NOT NULL DEFAULT 0,
  -- BaseEntity audit columns: date_created, date_updated, created_by_id,
  -- last_updated_by_id, is_deleted, deleted_at
  CONSTRAINT "PK_accounting_document_sequences" PRIMARY KEY ("id"),
  CONSTRAINT "UQ_accounting_document_sequences_scope"
    UNIQUE ("tenant_id", "workspace_id", "sequence_key")
);

CREATE INDEX "IDX_accounting_document_sequences_scope"
  ON "accounting_document_sequences" ("tenant_id", "workspace_id", "sequence_key");

The entity carries currentValue as bigint default 0; the unique index on ['tenantId', 'workspaceId', 'sequenceKey'] is what makes the upsert below atomic.

Allocation: `nextValue`

async nextValue(tenantId, workspaceId, sequenceKey): Promise<number>

A single SQL statement does an atomic upsert-and-increment:

INSERT INTO accounting_document_sequences
  (id, tenant_id, workspace_id, sequence_key, current_value, ...)
VALUES (uuid_generate_v4(), $1, $2, $3, 1, ...)
ON CONFLICT (tenant_id, workspace_id, sequence_key)
DO UPDATE SET current_value = accounting_document_sequences.current_value + 1,
              date_updated = now()
RETURNING current_value;

First allocation for a tuple inserts current_value = 1.
Every subsequent allocation hits the ON CONFLICT branch and increments by 1.
The statement RETURNING current_value, so the caller gets the freshly allocated number in one round-trip.
If the returned value isn’t a number (driver/SQL anomaly), the service throws with the offending sequenceKey, tenant and workspace so the failure is diagnosable.

Concurrency & gap-freeness

The design comment in the service spells out the contract:

Gap-free by design: row-level lock serializes concurrent callers per sequence key. PG sequences would be faster but allow gaps, which breaks regulatory compliance for invoices/bills.

The ON CONFLICT DO UPDATE takes a row-level lock on the conflicting row for the duration of the transaction. Concurrent allocators for the same tuple serialize on that lock and each observes a distinct, contiguous value — there are no gaps and no duplicates. Allocators for different tuples (different book, or different series) don’t contend. This is deliberately not a Postgres SEQUENCE: native sequences are faster but burn numbers on rollback, producing gaps that are unacceptable for statutory documents (invoices, bills). Here the counter only advances inside the committing transaction’s view because it is an ordinary row update.

Caveat for callers: because the increment is part of the surrounding transaction, allocating a number and then rolling the transaction back will not release the number unless the allocation itself is rolled back with it. Numbers are intended to be allocated at the point the document is persisted.

Formatting: `nextFormattedNumber`

async nextFormattedNumber(tenantId, workspaceId, sequenceKey, prefix, date = new Date()): Promise<string>

Wraps nextValue and formats:

return `${prefix}-${date.getFullYear()}-${String(nextValue).padStart(6, '0')}`;

So the canonical format is PREFIX-YYYY-NNNNNN — prefix, calendar year of the supplied date (defaults to now), then the raw counter zero-padded to 6 digits. Two things to note:

The counter is monotonic across years — it is not reset on January 1. The year in the string comes from date.getFullYear(), but current_value keeps climbing. INV-2025-000412 can be followed by INV-2026-000413.
getFullYear() is local-time, unlike the UTC date helpers used elsewhere in the reports service. Numbering is not timezone-critical, but be aware of the inconsistency if you ever reconcile a number’s year against a UTC posting date.

Call sites

Each numbered document type owns a distinct sequenceKey. Because the key is part of the unique tuple, every type counts independently within a book.

Document	Caller	`sequenceKey`	`prefix`	Example
Invoice	`invoices.repository.ts` `generateInvoiceNumber`	`invoices`	`INV`	`INV-2026-000001`
Bill	`bills.repository.ts` `generateBillNumber`	`bills`	`BILL`	`BILL-2026-000001`
Expense	`expenses.repository.ts` `generateReferenceNumber`	`expenses`	`EXP`	`EXP-2026-000001`
Journal entry	`journal.repository.ts` `generateEntryNumber`	`journal_entries`	`JE`	`JE-2026-000001`
Quotation	`quotations.repository.ts` `generateQuotationNumber`	`quotations`	`QTN`	`QTN-2026-000001`
Bank loan	`bank-loans.service.ts` `create`	`bank-loans`	`LN`	`LN-2026-000001`
Payment / Receipt	`payments.repository.ts` `generateReferenceNumber`	`payments:${prefix}`	caller-supplied	`RCP-2026-000001`
Petty-cash fund	`petty-cash.repository.ts` `generateFundNumber`	`petty_cash_funds`	— (custom format)	`PCF-0001`

Two non-standard cases

Payments namespace their key by prefix: payments:${prefix}. This means each payment prefix (e.g. PAY, RCP) gets its own counter, so receipts and outbound payments don’t share a running number even though they live in the same repository.
Petty-cash funds bypass nextFormattedNumber and call nextValue directly, then format as PCF- + the value zero-padded to 4 digits with no year segment (PCF-0001). If you need petty-cash fund numbers to match the standard PREFIX-YYYY-NNNNNN shape, this is the call site to change.

Adding a new numbered document type

Pick a unique sequenceKey string (≤ 100 chars) that no other document type uses — it is the third leg of the unique tuple.
Inject DocumentSequenceService into the repository/service that creates the document.
Call nextFormattedNumber(tenantId, workspaceId, '<your-key>', '<PREFIX>') at the point you persist the row, inside the same transaction.
No migration is needed — the table already exists and rows are created lazily on first allocation via the INSERT ... ON CONFLICT upsert.

No schema change is required per type because the counter rows are self-provisioning.

Overview

Getting Started

Basics

Master Data

Transactions

Periods & Compliance

Reports

Budgeting

Settings

Developer Guide

Document Numbering Internals

Where it lives

The storage model

Allocation: `nextValue`

Concurrency & gap-freeness

Formatting: `nextFormattedNumber`

Call sites

Two non-standard cases

Adding a new numbered document type

​Where it lives

​The storage model

​Allocation: nextValue

​Concurrency & gap-freeness

​Formatting: nextFormattedNumber

​Call sites

​Two non-standard cases

​Adding a new numbered document type

Where it lives

The storage model

Allocation: `nextValue`

Concurrency & gap-freeness

Formatting: `nextFormattedNumber`

Call sites

Two non-standard cases

Adding a new numbered document type