Shares & Equity

The Shares module is a configuration-driven ownership engine. It manages share products, share accounts, ownership movements, pledges and holds, dividend events, allocations, and the orchestration of accounting and related domain actions.

PinkApple does not hardcode share behavior from the product type name alone. At runtime, the system resolves the product's effective flag set and uses it to decide:

• which workflows are available
• which ownership components matter on the account
• which transactions are legal
• how dividends are allocated
• which governance and lending restrictions apply
• which integrations are required

Navigation

Operations: Shares → Share Accounts / Transactions / Dividends / Meetings

Administration: Administration → Shares → Share Products / Group Types / Flag Catalog / Tax Configs / GL Links / BU Restrictions / Posting Rules

What Shares Owns

The shares module owns:

• share product behavior
• ownership state and transaction history
• pledge, hold, and exit state
• dividend declaration, allocation, payout, and reinvestment orchestration
• flag-driven workflow resolution

Other PinkApple domains continue to own their own processes:

• Loans own loan applications, approvals, disbursement, repayment, and recovery
• Clients own holder eligibility, member status, employee status, KYC, age, and segment data
• Pricing owns fees, valuations, tiering, and pricing-driven dividend logic
• Shares Tax Configs own the approved tax-rate definitions linked directly to share products
• GL owns accounting rules, approval routing, and journal posting
• Deposits / Cash own funding and payout settlement channels
• Governance owns meetings, proxies, voting sessions, and resolutions

Product Model

Each share product is resolved from three layers:

1. Taxonomy defaults from the selected group/type entry
2. Allowed flags for that taxonomy
3. Product-level selected flags and values

The resolved flag set becomes the product's effective runtime behavior.

Example Runtime Decisions

Depending on the effective flags, the product may enable or restrict:

• transfers
• buybacks
• exits and refunds
• capital calls
• recurring contributions
• vesting
• voting
• pledges
• dividend eligibility and payout modes

Pricing Profile vs Tax Configuration

Share products now use two separate integration references:

• pricing_profile_id for pricing-engine behavior such as fees, valuation, and rate logic
• tax_profile_id for approved share tax configurations such as dividend withholding and other share-domain tax treatment

If taxation is enabled on the resolved runtime flags but no valid tax config is linked, runtime policy surfaces a blocking TAX_PROFILE_REQUIRED error.

Share Accounts

A share account represents a holder's ownership position under one share product.

Core ownership components include:

• total units
• paid-up units
• pledged units
• locked units
• available units

Flag-driven runtime state may also expose:

• vested units
• unvested units
• pending-exit units
• callable units
• dividend-eligible units
• governance-eligible units
• loan-pledged units
• transfer-blocked units

Share Transactions

Common transaction families include:

• issue / purchase
• contribution
• transfer
• buyback
• exit refund
• forfeiture
• call payment
• dividend reinvestment
• redemption
• adjustment
• fee

Approval and Posting Safety

Share transactions use the same deferred GL posting pattern used by other domain-driven posting flows.

That means:

• the share transaction is created first
• the accounting event is sent to the GL posting engine
• ownership effects are only applied after the GL outcome becomes terminal POSTED

If the GL batch is:

• PENDING_APPROVAL
• SCHEDULED_FUTURE_POST
• RETURNED
• REJECTED

then ownership state is not applied early.

This protects share balances from drifting away from the accounting outcome.

Dividends

Shares owns the dividend lifecycle:

1. declaration
2. allocation or hybrid run computation
3. approval
4. payment or reinvestment
5. audit history

PinkApple supports two production-ready distribution paths today:

• SHARE_DAYS for time-weighted share-only distributions
• HYBRID_SHARE_DEPOSIT_DAYS for hybrid member distributions that combine share value-days and qualifying deposit balance-days

Hybrid events still start from dividend_event, but they use a dedicated policy and run layer before a final run is synced into the normal dividend allocation table.

Use the product's effective dividend flags to determine which method applies. See:

• Share Product Flags
• Hybrid Share + Deposit Distributions

If the product uses taxation for dividend flows, the tax setup must come from Administration → Shares → Tax Configs, not from the pricing profile lookup.

Share-Backed Lending

When a shareholder wants a loan, the request still runs through the Loans domain.

Shares only supplies the lending side with:

• available pledgeable units
• loan-pledged units
• multiplier policy
• blocked exit state
• collateral constraints

Shares does not own the loan lifecycle.

Funding and Payout Routing

Shares uses existing settlement domains rather than creating a separate cash engine.

• share purchase funding can come from configured collection channels
• dividend payout can go to cash, deposit transfer, or reinvestment based on product and account settings
• reinvestment creates a share transaction that still follows the GL-safe deferred posting pattern

Next Guides

• Share Product Flags
• Share Admin Setup
• Hybrid Share + Deposit Distributions
• Loan Accounts
• GL Posting Approval