Last amended: 2026-08-02 Audience: product, accounting, developer
ADR 0023: BooksPlus Starter Chart Governs Dolibarr Account Crosswalks
Context
BooksPlus needs an approved starter chart for initial company setup. The chart must cover launch readiness and Inventory Summary without allowing account numbers, Dolibarr configuration, or an observed reference database to define BooksPlus accounting meaning.
Dolibarr remains the operational source system. BooksPlus remains the
accounting system of record. BooksPlus account identity is its immutable
internal account id. A Dolibarr database row id, stored account code, displayed
or padded code, label, or pcg_type is not BooksPlus account identity.
The current bp3-doli implementation discovers and converges a Dolibarr account
by entity, stable pcg_version, and stored account code. Its current semantic
mapping table resolves account_role + mapping_version + effective_from as of
an activity date. These are useful adapter behaviors, but neither mutable code
nor a generated Dolibarr row id can provide the stable source-account identity
needed for renumbering, migration, and reproducible provisioning.
The reference charts US-GAAP-BASIC and US-BASE, and the illustrative
120100 and 510100 bp3-doli accounts, are discovery evidence only. They do
not define the approved starter chart. The noncanonical role keys
expense.cost-of-goods-sold and asset.inventory.finished-goods must not be
preserved as BooksPlus truth.
Decision
BooksPlus owns the versioned standard starter chart, immutable BooksPlus account identity, canonical account-role assignments, and the authoritative company-scoped Dolibarr-to-BooksPlus crosswalk.
bp3-doli owns the Dolibarr source-account registry, the separately versioned Dolibarr projection, desired-state convergence, and Dolibarr-side mapping, configuration-history, drift, and reconciliation evidence. Its mapping data is a synchronized operational read model or proposal source; it is not an independent authority for BooksPlus account meaning.
Starter-chart installation uses the governed chart-of-accounts application services established by ADR 0017. Dolibarr projection is a separate reviewed operation. bp3-doli must not create BooksPlus accounts through direct database writes, submit ledger mutations, or infer BooksPlus meaning from Dolibarr account properties.
BooksPlus standard starter chart
The canonical chart key is booksplus.standard. Starter-chart versions are
durable upgrade identities and are not redefined after implementation:
| Version | Durable content |
|---|---|
1 |
The original 20-account chart accepted on 2026-07-17. |
2 |
Adds 10200 Cash for Deposit with repeatable clearing.receipts_for_deposit. |
3 |
Adds 12200 Prepaid Expenses, 20500 Payment Disbursements Clearing, and 20600 Goods Received Not Invoiced; changes expense.operating from singleton to repeatable. |
4 |
Adds 20700 Credit Card Payable, 42000 Interest Income, and 61000 Finance Charges for the accepted Banking and Finance boundary. |
Version 4 is the current canonical starter chart. Every account created by
the v4 installer has:
- status
active; - posting status
posting; - source
booksplus_standard; - an effective-from date selected for the company installation; and
- direct posting allowed for the initial release.
The control-account flag identifies summary control accounts but does not change account identity, role meaning, or the initial direct-posting rule. Opening balances remain journal activity and are not account master data.
BooksPlus-local collision adoption
Account origin is distinct from starter-chart adoption. An account created by
the installer has source booksplus_standard. A compatible pre-existing
account adopted through protected review retains its original source and
immutable account id and receives the starter row's company-scoped immutable
standard_account_key.
Starter-chart installation preflights all existing-code collisions before mutation. Compatibility depends on explicit account properties and role state, not code, name, number range, source, or prior activity. Every adoption is explicit, attributable, audited, conflict-visible, and idempotent. Incompatible accounts cannot be adopted.
The user may cancel, use reviewed account maintenance and retry, or retain the existing chart through an explicit reviewed-chart alternative. Pending collisions keep chart readiness blocked, and a collision resolution makes older chart and account-role acknowledgements stale. The binding workflow and compatibility rules are defined by the Starter Chart Installation Contract.
| Code | Name | Type | Normal balance | Control account | Canonical role assignments |
|---|---|---|---|---|---|
10000 |
Cash on Hand | asset |
debit |
no | cash.on_hand (repeatable) |
10100 |
Operating Bank | asset |
debit |
no | bank.operating (repeatable) |
10200 |
Cash for Deposit | asset |
debit |
no | clearing.receipts_for_deposit (repeatable) |
11000 |
Accounts Receivable | asset |
debit |
yes | receivable.trade (required_singleton) |
12000 |
Inventory | asset |
debit |
yes | inventory.general, inventory.input, inventory.output (each singleton) |
12100 |
Prepaid Inventory | asset |
debit |
no | asset.prepaid_inventory (singleton) |
12200 |
Prepaid Expenses | asset |
debit |
no | asset.prepaid_expenses (singleton) |
20000 |
Accounts Payable | liability |
credit |
yes | payable.trade (required_singleton) |
20500 |
Payment Disbursements Clearing | liability |
credit |
no | clearing.payment_disbursements (repeatable) |
20600 |
Goods Received Not Invoiced | liability |
credit |
no | liability.goods_received_not_invoiced (singleton) |
20700 |
Credit Card Payable | liability |
credit |
yes | liability.credit_card (repeatable) |
21000 |
Accrued Expenses | liability |
credit |
no | liability.accrued_expenses (singleton) |
22000 |
Sales Tax Payable | liability |
credit |
no | tax.sales_tax_payable (required_singleton) |
23000 |
Customer Deposits | liability |
credit |
no | liability.customer_deposits (singleton) |
24000 |
Unapplied Customer Cash | liability |
credit |
no | liability.unapplied_customer_cash (singleton) |
30000 |
Owner Equity | equity |
credit |
no | equity.default (singleton) |
31000 |
Retained Earnings | equity |
credit |
no | equity.retained_earnings (required_singleton) |
32000 |
Opening Balance Equity | equity |
credit |
no | none |
40000 |
Product Revenue | income |
credit |
no | revenue.product (required_singleton) |
41000 |
Service Revenue | income |
credit |
no | revenue.service (singleton) |
42000 |
Interest Income | income |
credit |
no | revenue.interest (singleton) |
50000 |
Cost of Goods Sold | expense |
debit |
no | expense.cost_of_goods_sold (required_singleton) |
51000 |
Inventory Adjustment | expense |
debit |
no | expense.inventory_adjustment (required_singleton) |
52000 |
Purchase Price Variance | expense |
debit |
no | expense.purchase_price_variance (required_singleton) |
53000 |
Inventory Fallback Clearing | expense |
debit |
no | clearing.inventory_fallback (required_singleton) |
60000 |
General Expense | expense |
debit |
no | expense.operating (repeatable) |
61000 |
Finance Charges | expense |
debit |
no | expense.finance_charges (repeatable) |
This table is the reviewed v4 chart data. Codes are strings. Their numeric appearance and grouping are presentation conventions and do not define type, normal balance, posting behavior, control status, or role.
The chart may be extended through approved accounting-standard, industry, and customer layers. Such extensions do not require every operational Dolibarr account to become part of the universal BooksPlus starter chart.
The standard starter chart intentionally defines no capital-project, fixed-asset, accumulated-depreciation, or depreciation-expense accounts. ADR 0024 defers that entire lifecycle beyond the initial release.
Inventory Summary readiness
A Dolibarr installation projected from the starter chart is not Inventory Summary export-ready until all six current InvAcct settings resolve through explicit canonical role mappings:
| InvAcct setting | Canonical Account Role Contract key | v4 BooksPlus account |
|---|---|---|
INVACCT_ACCOUNT_INVENTORY_RM |
inventory.input |
12000 Inventory |
INVACCT_ACCOUNT_INVENTORY_FG |
inventory.output |
12000 Inventory |
INVACCT_ACCOUNT_COGS |
expense.cost_of_goods_sold |
50000 Cost of Goods Sold |
INVACCT_ACCOUNT_ADJUSTMENT |
expense.inventory_adjustment |
51000 Inventory Adjustment |
INVACCT_ACCOUNT_PPV |
expense.purchase_price_variance |
52000 Purchase Price Variance |
INVACCT_ACCOUNT_FALLBACK |
clearing.inventory_fallback |
53000 Inventory Fallback Clearing |
Every export-ready starter-chart projection or profile must provide all six
mappings. None may be inferred from a code range, label, description,
pcg_type, product setting, or supplier-invoice evidence.
Raw-material and finished-goods roles may resolve to the same account unless an
approved accounting policy or industry profile requires separation. Starter
chart v4 retains both roles on 12000 Inventory.
The fallback mapping is review clearing for unsupported or unresolved output. Its presence must not convert an unknown movement into resolved accounting meaning or suppress review.
Dolibarr projection and account-code compatibility
The BooksPlus starter chart must be projectable into a separately versioned
Dolibarr accounting system identified by stable pcg_version.
The canonical BooksPlus code space is not permanently restricted by the
present InvAcct shell pattern [A-Za-z0-9._-]{1,64} or the current
bpconnector VARCHAR(64) mapping column. Instead, every Dolibarr projection
record must provide an explicit compatible Dolibarr stored code. That code
must satisfy both the current adapter boundary and the selected Dolibarr
runtime/schema constraints; the adapter's 64-character allowance is not a
promise that every Dolibarr version accepts that length. Identical BooksPlus
and Dolibarr codes are a convenience, not identity. The v4 default projection
may use the v4 BooksPlus codes unchanged because they satisfy the current
adapter boundary.
Codes must remain strings throughout configuration loading, provisioning, export, drift comparison, reconciliation, and crosswalk storage. Leading zeros must survive unchanged.
ACCOUNTING_MANAGE_ZERO, ACCOUNTING_LENGTH_GACCOUNT, and
ACCOUNTING_LENGTH_AACCOUNT may alter Dolibarr display, padding, shorthand
resolution, or auxiliary-code behavior. They do not alter the stored general
account code and must not alter source-account or BooksPlus identity.
Reconciliation must compare exact stored codes while also recording enough
formatting context to explain a displayed or padded value.
Each reviewed Dolibarr projection record must explicitly state:
- stable source-account identity and logical account key;
- entity and
pcg_version; - exact stored account code;
- Dolibarr label and
pcg_type; - active status;
- posting eligibility required by the consuming operation;
- the related BooksPlus chart account and canonical role keys, where relevant; and
- projection/configuration version.
The Dolibarr label, pcg_type, and posting eligibility are assigned by the
reviewed target-version projection. They must not be calculated from number
patterns or treated as canonical BooksPlus meaning.
Customer and supplier auxiliary codes, including generated values such as
411CUSTCODE and 401SUPPCODE, are Dolibarr operational identifiers. They
remain distinct from starter-chart codes, stable Dolibarr general-account
identity, and BooksPlus account identity.
Dolibarr journals, account formatting, product assignments, tax accounts, bank accounts, and third-party auxiliary accounts cannot establish BooksPlus workflow, role, or posting meaning.
Stable Dolibarr source-account identity
bp3-doli must assign each governed Dolibarr general account an opaque, durable
UUID named dolibarr_source_account_id. The UUID is generated or assigned
once, then stored; it is not recomputed from mutable account attributes. The
cross-system identity of a Dolibarr account is the pair of source-system
instance identity and this source-account id.
The id is bound to a stable logical account key in the bp3-doli source-account registry:
- standard and profile accounts receive a stable id and logical key in reviewed desired-state data;
- customer-overlay accounts receive an explicitly assigned stable id and logical key in governed customer configuration; and
- an adopted pre-existing account receives an id once through a reviewed adoption or migration record.
Standard/profile UUIDs are retained in reviewed desired-state data. Customer UUIDs are retained in governed private customer configuration. Adopted-account UUIDs are retained in the registry and migration evidence.
The source-account id and logical key must be preserved in normalized export,
configuration history, migration packages, backup/restore, and reproducible
provisioning. A renumber changes the observed stored code but not the source
account id. A rebuild reattaches the preserved id to the converged logical
account. A migration transports the id and its history. A pcg_version change
preserves the id only when an approved migration explicitly declares logical
account continuity; otherwise the projected account receives a new identity
and requires a new reviewed mapping.
Dolibarr rowid, stored or displayed code, label, pcg_type, chart position,
and a hash of mutable attributes must not be used as this identity. If the
registry identity is missing or conflicts with the discovered account, the
account must remain unmapped or be held for review; bp3-doli must not mint a
replacement identity and silently reuse the old mapping.
Current discovery by entity, pcg_version, and stored code remains a
compatibility mechanism for locating a row. It is not the governed identity
after adoption into the source-account registry.
Authoritative crosswalk
BooksPlus owns the authoritative crosswalk because it validates the target company, immutable BooksPlus account id, account status, posting eligibility, and canonical role assignment. bp3-doli may propose changes and retain a versioned operational read model and reconciliation evidence.
The crosswalk must preserve at least:
- company identity;
- Dolibarr source-system instance identity;
- stable
dolibarr_source_account_id; - Dolibarr logical account key;
- observed entity,
pcg_version, and exact stored code; - immutable BooksPlus account id;
- observed BooksPlus code for review;
- canonical role key where relevant;
- independently versioned mapping version;
- effective-from and effective-to dates;
- active/status state;
- creation and change attribution;
- reason or review reference; and
- audit and correlation reference when available.
Canonical role assignments remain attached to immutable BooksPlus account ids. The crosswalk may expose a role for governed resolution and review, but it must not replace the Account Role Assignment model.
The replacement for the current bpconnector natural key must retain independent mapping versions and activity-date resolution. Its governed scope must include company, source-system instance, stable source-account identity, mapping version, and effective-from date. Role-based operational resolution must also include company and source-system scope. The selected mapping version must be explicit in resolved configuration or the resolution request; a resolver must not infer it by choosing the newest row.
Effective intervals are inclusive. Within a selected mapping version, active intervals must not overlap for a given company, source system, source-account identity, and governed mapping purpose. More than one mapping version selected for the same scope and activity date is also ambiguous. A singleton canonical role must not resolve to multiple active source accounts for the same source system and activity date. A resolver must return exactly one applicable mapping. Zero matches is missing; more than one is ambiguous. Both outcomes fail the governed operation or remain reviewable. Selecting the most recent row silently is prohibited.
Crosswalk resolution must also reject or hold for review:
- wrong-company or wrong-source-system mappings;
- conflicting reuse of source-account identity, logical key, or mapping key;
- mappings to inactive, retired, non-posting, or otherwise ineligible BooksPlus targets;
- stale observations after a source or target change;
- incompatible renumbering; and
- product or supplier-invoice codes that disagree with the exact stored code and its recorded Dolibarr padding context.
Configuration precedence and protected meaning
Dolibarr desired configuration is resolved in this order:
base -> accounting standard -> industry profile -> customer overlay
Customer overlays may express approved company-specific code, label, or operational differences. They may not replace canonical roles, protected accounting controls, source-account identity, crosswalk rules, mapping history, or the precedence model.
Chart version, crosswalk/mapping version, bp3-doli configuration version,
Dolibarr runtime version, pcg_version, and integration-contract version are
independent. No version may be silently derived from another.
Lifecycle and convergence
Starter-chart installation and Dolibarr projection must be idempotent. Existing instances use ordered, idempotent migrations.
Renaming or renumbering preserves BooksPlus account identity, Dolibarr source-account identity, effective-dated mapping history, attribution, and audit evidence. Used accounts must not be deleted or silently replaced.
A desired-state account that is removed in a later version must be retired or reported for authorized review according to accepted account policy. Missing, stale, ambiguous, inactive, conflicting, or incompatible mappings must fail or remain reviewable; provisioning and reconciliation must not repair them silently.
Provisioning, validation, normalized export, drift detection, reconciliation, and configuration-history evidence must cover both projected chart state and the source-account/crosswalk read model.
Controlled propagation is one-way per approved change:
- A BooksPlus change preserves immutable identity and audit history.
- Crosswalk validity is reevaluated.
- Any Dolibarr change becomes reviewed desired state or an ordered migration.
- bp3-doli converges and validates Dolibarr, then records reconciliation evidence.
A Dolibarr-originated change may become a proposal, but a change affecting BooksPlus type, role, posting eligibility, or status always requires authorized BooksPlus chart review. No automatic bidirectional mutation loop is allowed.
Security and audit
Starter-chart installation, chart import commit, account maintenance, role assignment, crosswalk adoption or change, source-account identity assignment, and approved projection changes are protected accounting-configuration actions. They require company and actor context, policy-based authorization, and append-only audit evidence.
Denied changes and reconciliation conflicts must remain explainable. Raw credentials, sensitive payloads, and customer-identifying data must not be written to logs or public version-controlled chart artifacts.
Consequences
Positive consequences:
- Starter-chart version history and current v4 content and role assignments are reviewable canonical truth.
- All six current InvAcct mappings are explicit and mandatory for export readiness.
- BooksPlus and Dolibarr may renumber accounts without losing either system's identity or mapping history.
- Broader future BooksPlus codes remain possible behind an explicit compatible Dolibarr projection code.
- Padding, stale mappings, and overlapping effective dates become visible reconciliation concerns instead of silent selection rules.
Costs and tradeoffs:
- bp3-doli needs a durable source-account registry in addition to current code-based discovery.
- BooksPlus needs authoritative crosswalk persistence and a synchronization boundary for bp3-doli's operational read model.
- Projection and mapping changes require coordinated review, migration, and reconciliation.
- Dolibarr-specific
pcg_type, formatting, and posting details remain explicit projection data rather than being inferred cheaply from the chart code.
Amended on 2026-07-29 to accept starter-chart version 4 and the
liability.credit_card, revenue.interest, and
expense.finance_charges accounts and role assignments required by the
canonical Banking and Finance boundary.
Amended on 2026-08-02 to distinguish account origin from reviewed starter-chart adoption and to govern BooksPlus-local collision resolution.
Implementation boundary
This ADR accepts product meaning and reviewed chart data. It does not authorize chart provisioning or BooksPlus/bp3-doli implementation by itself. A later implementation pass must compare this accepted truth with current code and configuration, identify migrations, and add tests before changing either product.
Related truth and decisions
../../accounting/accounts.md../../contracts/account.contract.md../../contracts/account-role.contract.md../../contracts/account-code-resolution.contract.md../../contracts/chart-import.contract.md../../contracts/starter-chart-installation.contract.md../../contracts/dolibarr-account-crosswalk.contract.md0001-used-records-are-retired-not-deleted.md0004-canonical-accounting-model-is-source-of-truth.md0007-provider-agnostic-import-boundaries.md0012-policy-based-authorization.md0014-append-only-security-audit-events.md0017-chart-maintenance-surrounds-accounting-kernel.md0024-operational-summary-workflow-boundaries-and-purchasing-facts.md../../contracts/banking-and-finance-summary-fact.contract.md../../../planning/bp3-starter-chart-templates.md