# Account Lifecycle

## Overview

GL accounts follow a state machine (DRAFT -> ACTIVE <-> INACTIVE) that governs when an account can receive journal postings, be modified, or be deactivated. The lifecycle ensures that accounts are fully validated before they participate in financial transactions, and that historical data is preserved when an account is retired.

Accounts with posted transactions cannot be deleted — they must be deactivated instead. Deactivation prevents new postings while retaining the account for regulatory reporting and audit purposes. An optional successor account mapping allows a replacement to be designated during deactivation; the actual posting redirection behavior is owned by the general-ledger module, which reads the successor mapping from this module. All status transitions emit audit events through the audit module, supporting SOX compliance requirements for change tracking on the chart of accounts.

## Business Purpose

- **Lifecycle gating**: Only ACTIVE accounts can receive new journal postings, preventing use of incomplete or retired accounts in financial transactions. Account activation itself requires the parent CoA to be in ACTIVE status — accounts under a DRAFT CoA remain in DRAFT until the CoA is activated, ensuring safe cascade deletion of DRAFT CoAs
- **Data preservation**: Accounts with posted transactions are never deleted; deactivation preserves history for regulatory retention requirements (typically 7-10 years)
- **Deprecation with successor mapping**: When retiring an account, an optional successor account can be designated. This module stores the mapping; the general-ledger module is responsible for reading this mapping and redirecting future postings
- **Balance verification (integration point)**: Deactivation can optionally verify that the account carries no open or unreconciled balances. The balance truth is owned by the general-ledger module — this module exposes a hook for the GL module to block deactivation when open balances exist
- **Audit trail**: Every status transition is recorded via the audit module, providing a complete change history for internal controls and external audits
- **Segregation of duties**: Account creation, modification, and approval of status changes can be assigned to separate roles, satisfying SOX and internal control requirements

## Process Flow

```mermaid
stateDiagram-v2
    [*] --> Draft: createAccount
    Draft --> Active: activateAccount
    Active --> Inactive: deactivateAccount
    Inactive --> Active: reactivateAccount
    Draft --> [*]: deleteAccount
```

```mermaid
stateDiagram-v2
    state "Deactivation Workflow" as deact {
        [*] --> VerifyBalances: initiate deactivation
        VerifyBalances --> MapSuccessor: no open balances
        VerifyBalances --> Blocked: open balances exist
        MapSuccessor --> SetInactive: successor mapped (optional)
        SetInactive --> EmitAuditEvent
        EmitAuditEvent --> [*]
        Blocked --> [*]: resolve balances first
    }
```

## Scenario Patterns

- **New Account Setup**: A controller creates a GL account in DRAFT, assigns it to the correct account group and hierarchy, then activates it once the parent CoA is ACTIVE (account activation is gated on CoA ACTIVE status) before the first posting period
- **Account Deprecation with Successor**: A revenue account is being replaced by a more granular set of accounts; the old account is deactivated with a successor mapped. The general-ledger module reads this mapping to redirect any future automated postings to the new account
- **Balance-Blocked Deactivation (with GL integration)**: An attempt to deactivate an expense account is blocked by the general-ledger module's balance check hook because it still carries an unreconciled balance; the balance must be cleared or transferred before deactivation can proceed
- **Seasonal Reactivation**: A project-specific account was deactivated at project close but is reactivated when the project resumes, avoiding a duplicate account
- **Draft Cleanup**: An account created in error is deleted while still in DRAFT before any transactions are posted against it
- **Regulatory Retention**: A long-inactive account remains in the system with full posting history to satisfy the organization's 7-year data retention policy

## Test Cases

- Account lifecycle follows DRAFT -> ACTIVE <-> INACTIVE state machine
- Accounts can only be created in DRAFT status
- Only DRAFT accounts with no posted transactions can be deleted
- Activating a DRAFT account transitions status to ACTIVE when the parent CoA is ACTIVE
- Activating an account under a DRAFT CoA fails because account activation requires the parent CoA to be in ACTIVE status
- Activating an account under an ARCHIVED CoA fails because archived CoAs are immutable
- Activating an already ACTIVE account fails with an invalid status transition error
- Deactivating an ACTIVE account transitions status to INACTIVE
- Deactivating a DRAFT account fails with an invalid status transition error
- Reactivating an INACTIVE account transitions status to ACTIVE
- Only ACTIVE accounts can receive new journal postings
- Deactivation exposes a pre-deactivation hook that the general-ledger module can use to block the transition when open or unreconciled balances exist
- Without a GL module integrated, deactivation proceeds without balance checks
- A successor account can be mapped during deactivation; posting redirection is owned by the general-ledger module
- The successor account must itself be ACTIVE at the time of mapping
- A successor account mapping is optional; deactivation succeeds without one when balances are clear
- Deleting an account that has posted transactions fails regardless of current status
- Each status transition emits an audit event via the audit module
- Audit events record the previous status, new status, acting user, and timestamp
- Reactivating an account clears any previously mapped successor account
- Inactive accounts and their posted transactions remain queryable for reporting

## Reference Links

- [SAP GL Account Master Data](https://help.sap.com/docs/SAP_S4HANA_ON-PREMISE/ee8e4a0f52db415aaa43eb0bf5446a35/4b0a1e1c2d6b3e41e10000000a42189c.html)
- [Odoo Chart of Accounts](https://www.odoo.com/documentation/19.0/applications/finance/accounting/get_started/chart_of_accounts.html)
- [Oracle GL Account Maintenance](https://docs.oracle.com/en/cloud/saas/financials/24d/oafmg/overview-of-oracle-general-ledger.html)
- [SOX Section 302 — Internal Controls](https://www.sarbanes-oxley-101.com/sarbanes-oxley-compliance.htm)
