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 / 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, taxes, valuations, tiering, and pricing-driven dividend logic
• 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

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
3. approval
4. payment or reinvestment
5. audit history

PinkApple currently keeps SHARE_DAYS as the primary computation path, while the product flag model supports broader methods such as:

• snapshot balance
• average balance
• fixed rate
• fixed amount per unit
• tiered rate
• pricing-driven
• patronage formula
• hybrid

Use the product's effective dividend flags to determine which method applies. See Share Product Flags for the configuration model.

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
• Loan Accounts
• GL Posting Approval