Deposit Product Flags

Flag-driven product configuration for the deposit domain.

Overview

Deposit products in Pinkapple use a flag-driven architecture to control account behavior. Instead of hardcoding product variants (e.g. "Senior Citizen FD", "Green FD"), behavior is composed from reusable flags that can be enabled, disabled, or configured per product type and per individual product.

Architecture

Resolution Chain

When the system needs to determine a product's effective configuration, flags are resolved in priority order:

1. PRODUCT — Per-product overrides (deposit_product_flag_config)
2. TYPE_DEFAULT — Default values for the product type (deposit_type_default_flag_profile)
3. LEGACY_PRODUCT — Legacy product_config_flags JSON on deposit_product
4. LEGACY_TYPE — Legacy custom_flags + product_characteristics JSON on deposit_product_group_type_map
5. CATALOG_DEFAULT — Master flag definition defaults (deposit_flag_catalog)

Tables

Table	Purpose
deposit_flag_catalog	Master flag definitions (code, name, type, defaults, UI metadata)
deposit_flag_value_option	ENUM option labels for flags
deposit_type_allowed_flag	Which flags are allowed per product group/type
deposit_type_default_flag_profile	Default flag values per product type
deposit_product_flag_config	Per-product flag overrides

Flag Groups

Group	Flags	Purpose
LIMITS	9 flags	Balance limits, transaction caps, monthly count limits
ACCESS	6 flags	ATM, mobile, online, checkbook, debit card, branch
OVERDRAFT	4 flags	Negative balance, OD allowed/limit, OD interest
KYC	7 flags	KYC level, biometric, residency, employment, age
INTEREST	6 flags	Interest bearing, rate type, payout frequency, compounding, WHT
FIXED_DEPOSIT	12 flags	Term, tenure, withdrawal, penalty, rollover, maturity
SAVINGS_PLAN	5 flags	Goal-based, installments, missed payments
COMMUNITY	3 flags	Group accounts, pooled funds, rotation schedule
GOVERNANCE	2 flags	Joint accounts, signatories
DORMANCY	3 flags	Detection, inactivity days, dormancy fees
INTEGRATION	5 flags	GL, pricing engine, sweeps, wallet, agent banking
REGULATORY	3 flags	Tax exemption, green certification, deposit insurance
TRIGGER_EVENTS	4 flags	Pricing triggers per transaction type, GL callbacks

Product Types (Simplified)

The system ships with 18 core product types across 7 groups:

Group	Types
FIXED_DEPOSIT	Standard, Flexible, Periodic Payout, Cumulative
SAVINGS_ACCOUNT	Basic, High Yield, Digital, SACCO
SAVINGS_PLAN	Goal-Based, Recurring, Micro
CURRENT_ACCOUNT	Personal, Business, Salary
STORED_VALUE	Wallet
FUNDING_ACCOUNT	Operational
COMMUNITY_FINANCE	VSLA, ROSCA

Variants that previously existed as separate types (e.g. "Senior Citizen FD", "Green FD", "Tax Saver FD") are now created as standard products with flag overrides.

How It Works

Creating a Deposit Product

1. Select a Product Classification (group/type) from the type catalog
2. The form automatically loads the type flag profile — which flags are available, which start enabled, and their default values
3. Override individual flags as needed for this specific product
4. On submit, both the legacy product fields AND the flag configs are saved

Runtime Resolution

When a procedure needs to check a product's flags (e.g. during account opening, transaction processing, or EOD batch):

CALL resolve_deposit_product_flags(
  @deposit_product_id,
  @effective_flags,    -- OUT: flat JSON object { "flag_code": value }
  @flag_details        -- OUT: detailed array for debugging
);

The procedure builds a temp table tmp_deposit_flag_resolution that can be queried directly for complex flag-dependent logic.

Affects Metadata

Each flag declares which subsystems it affects via affects_* boolean columns:

Column	Subsystem
affects_account_state	Account lifecycle / status
affects_workflow	Approval or process workflows
affects_transactions	Transaction processing
affects_interest	Interest accrual / capitalisation
affects_fees	Fee calculation / charging
affects_gl	GL posting engine
affects_pricing	Pricing engine integration
affects_limits	Transaction / balance limits
affects_maturity	FD maturity processing
affects_dormancy	Dormancy detection
affects_onboarding	Account opening / KYC

API Endpoints

Method	Path	Description
GET	/flag-catalog	List flag catalog (paginated, filterable by group)
POST	/flag-catalog	Create new flags
PUT	/flag-catalog	Update existing flags
DELETE	/flag-catalog	Soft-delete flags
GET	/effective-flags	Resolve effective flags for a product

All endpoints are under /api/administration/products/deposit-products/.

Frontend Integration

The DepositProductFlagConfigEditor.vue component is integrated into the deposit product form as a custom section. It:

1. Watches the selected product taxonomy (group/type)
2. Loads the type's flag profile (from seeded data or via API)
3. Renders flags grouped by flag_group with appropriate editors
4. Shows a Runtime Preview card summarizing enabled features
5. Syncs flag configs to the form engine for submission

Pricing Engine Integration

Flags in the TRIGGER_EVENTS group control when the pricing engine is invoked:

• PRICING_TRIGGER_ON_DEPOSIT — Evaluate fees on deposit transactions
• PRICING_TRIGGER_ON_WITHDRAWAL — Evaluate fees on withdrawal transactions
• PRICING_TRIGGER_ON_TRANSFER — Evaluate fees on transfer transactions
• GL_CALLBACK_ON_POST — Enable GL callback dispatch after posting

These flags work with the existing pricing_binding and gl_domain_callback systems.