Share Product Flags

Share products in PinkApple are flag-driven. The system does not assume behavior from the share type name alone.

At runtime, the product's effective behavior is resolved from:

1. the selected seeded share type taxonomy
2. the flags attached to that type
3. the product's override values for flags that the type allows product-level editing
4. legacy compatibility fields still stored on the product

Where To Configure

Use these administration pages together:

• Administration → Shares → Type Taxonomy
• Administration → Shares → Share Products
• Administration → Shares → GL Links
• Administration → Shares → Posting Rules

Flag Layers

Group Type Profiles

Each seeded type entry defines:

• which flags are allowed for that taxonomy
• whether each flag is enabled by default
• whether the flag is required
• whether product setup users can edit it

Product Flag Configuration

At product setup, the user first selects a share type. PinkApple then loads the flags allowed for that type.

The product form now includes a Runtime Flags & Integrations section that lets you:

• review the flags inherited from the selected type
• enable or disable only the flags that the type marks editable on the product
• set values for enum, array, number, JSON, and text flags
• preview the resolved runtime behavior

There is no end-user UI for creating or editing the master flag catalog. Those definitions are seeded into the platform.

Main Flag Groups

PinkApple currently organizes share flags around these domains:

• Identity
• Clients
• Transfer
• Exit
• Acquisition
• Contribution
• Vesting
• Governance
• Lending
• Dividend

Runtime Preview

The product form includes a runtime preview that summarizes:

• enabled workflows
• account components that will matter at runtime
• dividend treatment
• governance rights
• lending and restriction implications

Use this preview before approving or activating a product.

Type First, Product Second

The expected operating model is:

1. review the seeded type taxonomy
2. create a share product from one of those types
3. override only the flags that are product-editable for that type
4. use the preview to confirm the final runtime behavior

This keeps share behavior consistent across products of the same class while still allowing controlled product specialization.

Common Examples

SACCO Mandatory Capital

Typical settings include:

• transfer disabled
• notice-based exit
• recurring contribution enabled
• voting enabled on one-member-one-vote basis
• loan multiplier enabled
• dividend classification set to patronage or share-days logic

Preference Shares

Typical settings include:

• transfer limited to same class or approval-required
• dividend classification set to priority
• computation method set to fixed rate or hybrid
• redemption rights enabled where relevant

Employee Shares

Typical settings include:

• employee status required
• vesting enabled
• transfer restricted
• dividend eligibility controlled by vested-unit rules

Integration Expectations

Flags can drive integration expectations, but the target domain still owns the logic.

• Clients flags enforce holder eligibility rules
• Pricing integration points to pricing profiles for fees, valuation, and rate logic
• Taxation integration points to approved share tax configurations for withholding and other share tax rules
• Lending flags control pledge and exit restriction behavior
• GL-related flags influence which accounting flows are expected

Pricing And Tax Configuration

Two different references are involved when integrations are enabled:

• pricing_profile_id links to Pricing Profiles
• tax_profile_id links to Share Tax Configurations

They are not interchangeable.

What The Platform Enforces

• If PRICING_INTEGRATION_ENABLED resolves to true, the product must link to an approved active pricing profile.
• If TAXATION_ENABLED resolves to true, the product must link to an approved tax configuration whose effective dates cover the current date.
• If taxation is enabled with no tax config, runtime policy returns a TAX_PROFILE_REQUIRED blocker.
• If pricing or tax references are invalid, create and update stop with a controlled validation error instead of relying on raw FK failures.

Dividend Flags

Important dividend-related flags include:

• classification
• computation method
• pool source
• eligible unit basis
• exclusion rules
• priority rank
• payment modes

The shares module orchestrates the event and allocation history. Pricing continues to own pricing-engine rates and tiers, while share tax configurations own the product-level tax reference used by share operations.