Skip to content

Source truth: - Company Identity and Context Contract - Journal Entry Contract - Source Document Contract - Money Contract - Actor Identity Contract - Roles and Permissions Contract - Protected Actions Contract - Security Audit Event Contract - ADR 0011: Desktop Identity Model - ADR 0012: Policy-Based Authorization

API Design

This page describes API design principles for BooksPlus.

  • Keep APIs aligned with canonical contracts.
  • Expose clear validation errors for accounting rules.
  • Preserve source references in API payloads.

Developer test identity plan

BooksPlus should support a developer/test identity for local development and automated testing, but that identity should use the normal actor, company, permission, policy, and audit paths.

The developer identity should not be a hidden bypass, hard-coded administrator shortcut, or production support account.

Goal

Provide a predictable actor and company context that can exercise all protected application functions in tests without weakening the production authorization model.

Proposed model

  • Seed or resolve the persisted development/test company record named BooksPlus Test Company.
  • Seed a local-only actor named Developer Test User.
  • Mark the actor as an explicitly defined application user or mapped local operating system user, according to the desktop identity model.
  • Assign the actor to the persisted BooksPlus Test Company company identity.
  • Grant the actor a test role or permission bundle named Developer Test Full Access.
  • Keep permissions explicit and policy-based, even when the bundle grants broad authority.
  • Emit normal audit events when the developer actor performs protected actions.
  • Make the seeded company, actor, and permission bundle unavailable in production company data unless an explicit development or test mode is active.

Company context

Company identity and company context are defined by the Company Identity and Context contract.

The developer test identity depends on the company identity slice. BooksPlus Test Company should be an ordinary persisted company record with stable company identity, allowed company status, base currency, creation context, and retirement behavior. It should not be represented only as an in-memory display name or implicit default company.

Development/test fallback company context may resolve BooksPlus Test Company only when explicit development or test mode is active. The desktop shell resolves the actor first, then creates or selects the company, and only then constructs company-scoped workflows. Production configuration may preselect an available company but is not required for first run and must not bypass actor assignment or visible administrator bootstrap.

Returning to company selection ends the current presentation session without changing company data. Entering the same or another authorized company must construct fresh company-scoped workflows and replace company-scoped presentation state; registers, forms, selections, drilldowns, and prepared commands from the prior company must not be reused.

Every API command that can affect accounting, security, auditability, backup, or sensitive data should carry or resolve:

  • actor identifier;
  • company identifier;
  • protected action or policy name;
  • target object identifier when applicable;
  • correlation identifier for multi-step workflows.

The API boundary should reject protected commands that do not resolve to both an actor and a company context, except for explicitly company-creation or company-selection flows.

Company-scoped audit events should store the resolved company identifier.

Permission bundle

The developer test bundle should be generated from the protected action registry rather than maintained as a separate hard-coded list.

This keeps tests aligned with new protected actions. If a new protected action is added, the developer test bundle should either include it intentionally or fail setup until the permission decision is made.

The initial protected action registry should include:

  • AccountingEntry.Post;
  • AccountingEntry.Reverse;
  • Period.Close;
  • Period.Reopen;
  • ChartOfAccounts.Change;
  • FiscalCalendar.Change;
  • AccountingPolicy.Change;
  • CompanyData.Export;
  • Backup.Create;
  • Backup.Export;
  • Backup.Restore;
  • User.Manage;
  • RolePermission.Change;
  • AuditLog.View;
  • SupportAccess.Grant.

Testing approach

  • Use the developer actor for happy-path coverage of protected workflows.
  • Add separate negative tests with narrower actors to prove policies are enforced.
  • Assert that sensitive actions emit audit events with the developer actor and company context.
  • Assert that disabling or retiring the developer actor blocks further protected actions.
  • Assert that the developer identity cannot be created or activated in production mode by ordinary application flows.

Alternative considered

A built-in developer actor type with unconditional access would be faster to wire, but it would bypass the policy model and make tests less representative. The preferred approach is a seedable test actor with explicit broad permissions because it exercises the same authorization and audit behavior that production users rely on.