---
id: WF-ACC-BKS-001
title: Create a Unit With Initial Calendar Coverage
trigger: A permitted caller submits a new business unit from the console or API.
product_area: accounting
module: books
revision: 1
status: draft
design_intent: proposed
implementation_evidence: observed
inference: []
source_sha:
  services-accounting: f47cb263875bbc0c5640fba7dae6785ec32695f8
  react-console: baf6dae382d6f41dce976c7f848667ccc37e076f
implements:
  - CAP-ACC-BKS-001
  - CAP-ACC-BKS-002
  - CAP-ACC-BKS-003
  - CAP-ACC-BKS-009
moves:
  - STATE-ACC-BKS-001
  - STATE-ACC-BKS-002
crosses: []
idempotency: >-
  There is no request idempotency key. A successful repeat under the same
  derived or supplied code is refused as a duplicate; a changed code can create
  another unit.
concurrency: >-
  Creation relies on primary-key uniqueness for racing codes. Its database
  writes share one transaction, so no reader sees a partially committed
  creation.
hops:
  - 'n': 1
    actor_or_service: Books service (request mapping)
    action: >-
      Validate the request and identifier, supported-set limits and
      multicurrency requirements.
    anchor: >-
      services-accounting:modules/books/services/persistence/business-units.ts:createBusinessUnit
    seam: sync
    on_failure: >-
      Refuse invalid input with a field-specific validation response before
      writes begin.
    left_inconsistent: No unit has been written.
    observer: the caller (console form errors)
    provenance: test
    source: >-
      services-accounting:modules/books/tests/integration/services/persistence/business-units.integration.spec.js#refuses
      Enable Multicurrency on a create with no supported currency, in Rhythm
      1.0’s words
  - 'n': 2
    actor_or_service: Books service (transaction)
    action: >-
      Check any named fee product for active same-unit ownership; database
      checks enforce fee completeness on insertion.
    anchor: >-
      services-accounting:modules/books/services/persistence/business-units.ts:assertCardFeeRule
    seam: sync
    on_failure: Return a fee-property validation error and roll back the transaction.
    left_inconsistent: No creation writes commit.
    observer: the caller
    provenance: test
    source: >-
      services-accounting:modules/books/tests/integration/services/persistence/business-units.integration.spec.js#refuses
      a fee product of another unit, an inactive one and one the tenant does not
      have, naming card_fee_product_id
  - 'n': 3
    actor_or_service: Books service and database
    action: >-
      Insert the unit, let the base-currency trigger run and write supported
      currency settings.
    anchor: >-
      services-accounting:modules/books/db/business-units.table.ts:business_units_base_currency_trigger
    seam: sync
    on_failure: >-
      Translate recognized identity or reference failures and roll back
      creation.
    left_inconsistent: Neither unit nor owned setup remains partially saved.
    observer: the caller
    provenance: test
    source: >-
      services-accounting:modules/books/tests/e2e/business-units.e2e.spec.js#creates
      it under the id its name suggests, in the tenant of the path
  - 'n': 4
    actor_or_service: Books service (fiscal calendar)
    action: >-
      Generate the fiscal year containing the workspace date and the following
      year, with twelve open periods each.
    anchor: >-
      services-accounting:modules/books/services/persistence/fiscal-years.ts:generateFiscalYearsInTransaction
    seam: sync
    on_failure: Roll back the complete creation if generation cannot finish.
    left_inconsistent: The attempted unit and calendar remain absent.
    observer: the caller
    provenance: test
    source: >-
      services-accounting:modules/books/tests/integration/services/persistence/fiscal-years.integration.spec.js#gives
      the new unit exactly its two years, the one containing today and the next
  - 'n': 5
    actor_or_service: Database (commit)
    action: Validate the committed calendar shape and complete the transaction.
    anchor: >-
      services-accounting:modules/books/db/fiscal-years.table.ts:fiscal_years_periods_trigger
    seam: sync
    on_failure: Roll back all writes if structural calendar checks fail.
    left_inconsistent: No part of this creation commits.
    observer: the caller
    provenance: observed
    source: >-
      services-accounting:modules/books/db/fiscal-years.table.ts:fiscal_years_contiguity_trigger
  - 'n': 6
    actor_or_service: Console
    action: >-
      Refresh shared Accounting reads so the new unit becomes available to
      appropriate selectors.
    anchor: >-
      react-console:components/configuration/resources/accounting-business-units.tsx:revalidateAccountingReads
    seam: sync
    on_failure: >-
      A failed refresh can require reload or a fresh selection; it does not undo
      the server save.
    left_inconsistent: Only the client’s displayed choices can remain stale.
    observer: the person
    provenance: documented
    source: 'services-accounting:docs/milestones/ACCT-M1-books-and-invoices.md#R28'
branches:
  - condition: Use default settings
    path: >-
      Apply active, single-currency, accrual, no costing, direct bad-debt
      treatment, summary download, Other software and no project inheritance
      when those choices are omitted.
waits: []
evidence:
  - >-
    services-accounting at f47cb263:
    modules/books/services/persistence/business-units.ts, fiscal-years.ts;
    db/business-units.table.ts, fiscal-years.table.ts
  - >-
    react-console at baf6dae3:
    components/configuration/resources/accounting-business-units.tsx
controls: [TC-IAM-001, TC-IAM-002, TC-IAM-004, TC-IAM-005, TC-AZ-001, TC-AZ-002, TC-AZ-003, TC-AZ-004, TC-AZ-005, TC-AZ-006, TC-TEN-001, TC-TEN-002, TC-TEN-003, TC-TEN-004, TC-DAT-001, TC-LOG-001, TC-LOG-002, TC-LOG-003, TC-LOG-004, TC-LOG-005, TC-PI-001, TC-PI-002, TC-PI-003]
---

# Create a Unit With Initial Calendar Coverage

## What It Does

Creating a unit establishes its founding currency and fiscal boundary together with initial calendar coverage. The base and supported currency rows and two complete fiscal years commit with the unit. This gives subsequent configuration and dated work a consistent starting point.

## The Flow

```mermaid
flowchart TD
  h0["Validate the request and identifier, supported-set limits and multicurrency requirements."]
  h1["Check any named fee product for active same-unit ownership; database checks enforce fee completeness on insertion."]
  h0 --> h1
  h2["Insert the unit, let the base-currency trigger run and write supported currency settings."]
  h1 --> h2
  h3["Generate the fiscal year containing the workspace date and the following year, with twelve open periods each."]
  h2 --> h3
  h4["Validate the committed calendar shape and complete the transaction."]
  h3 --> h4
  h5["Refresh shared Accounting reads so the new unit becomes available to appropriate selectors."]
  h4 --> h5
```

## When Something Fails

Input checks precede the transaction; every creation write shares that transaction. A refusal leaves no partial new unit. A duplicate retry after success fails under the same code, while a retry using a new code creates a distinct unit. Refreshing the console happens after commit and can leave the display stale without changing stored configuration.

## Open Design Questions

The generated coverage is relative to the creation date. A unit opened near its year boundary may need an explicit extension soon afterward; the product has no examined early warning.