Deposit Account Status FSM

The deposit account lifecycle is governed by a finite-state machine (FSM) that enforces valid status transitions at the SQL procedure level.

Statuses

Status	Description
PENDING	Account created, awaiting activation
APPROVED_PENDING_FUNDING	Fixed-deposit account approved, awaiting initial funding
ACTIVE	Normal operating state
DORMANT	Inactive beyond the dormancy threshold (automated)
FROZEN	Manually frozen — no transactions allowed
MATURED	Fixed-deposit term completed (automated)
CLOSED	Terminal state — account closed

Transition Matrix

PENDING ──ACTIVATE──▶ ACTIVE
PENDING ──ACTIVATE──▶ APPROVED_PENDING_FUNDING  (Fixed Deposits)
PENDING ──CLOSE────▶ CLOSED

APPROVED_PENDING_FUNDING ──ACTIVATE──▶ ACTIVE  (after funding)
APPROVED_PENDING_FUNDING ──CLOSE────▶ CLOSED

ACTIVE ──CLOSE──────▶ CLOSED
ACTIVE ──FREEZE─────▶ FROZEN
ACTIVE ──GO_DORMANT─▶ DORMANT  (automated)
ACTIVE ──MATURE─────▶ MATURED  (automated, FD)

DORMANT ──REACTIVATE─▶ ACTIVE
DORMANT ──FREEZE─────▶ FROZEN
DORMANT ──CLOSE──────▶ CLOSED

FROZEN ──UNFREEZE────▶ ACTIVE
FROZEN ──REACTIVATE──▶ ACTIVE
FROZEN ──CLOSE───────▶ CLOSED

MATURED ──CLOSE──────▶ CLOSED

CLOSED ──REACTIVATE──▶ ACTIVE

Actions & SQL Procedures

Action	Procedure	Allowed From
ACTIVATE	activate_deposit_accounts	PENDING, APPROVED_PENDING_FUNDING
CLOSE	close_deposit_accounts	ACTIVE, APPROVED_PENDING_FUNDING, DORMANT, FROZEN, MATURED, PENDING
FREEZE	freeze_deposit_accounts	ACTIVE, DORMANT
UNFREEZE	unfreeze_deposit_accounts	FROZEN
REACTIVATE	reactivate_deposit_accounts	CLOSED, DORMANT, FROZEN
MATURE	EOD maturity processing	ACTIVE
GO_DORMANT	EOD dormancy detection	ACTIVE

Centralised Validation

A shared helper procedure validate_deposit_account_status_transition can be called from any procedure that needs to guard a status change:

CALL validate_deposit_account_status_transition(
  v_account_id,
  'FREEZE',       -- action
  v_old_status    -- current status read from deposit_account
);
-- If the transition is illegal, SIGNAL 45000 is raised.

FSM Matrix API

The full matrix can be retrieved at runtime via:

GET /deposit-accounts/fsm-matrix

Returns an array of { action, source_status, target_status } rows.

Frontend Component

Use <DepositAccountStatusFsm /> from components/DepositAccountStatusFsm.vue to render the interactive transition diagram. It:

• Fetches the matrix from the API (falls back to a hardcoded copy)
• Colour-codes statuses and actions
• Allows filtering by clicking a source status node

Design Decisions

1. CLOSE is widely reachable — closing is an administrative escape hatch. Even PENDING accounts can be closed (e.g., opened in error).
2. FREEZE only from ACTIVE/DORMANT — freezing a PENDING or MATURED account is semantically incorrect.
3. REACTIVATE from CLOSED — some institutions allow reopening closed accounts. The procedure enforces this at the DB level; business policy can further restrict via permissions.
4. Automated transitions (MATURE, GO_DORMANT) are triggered only by EOD batch procedures, never by user-facing actions.