Data Model: Investment

Purpose: The Investment entity records one Investor's commitment to a Fund. It links the Investor's Profile to the Fund and tracks the amount, documents, and funding status.

Fields/Attributes

Name	Type	Description	Validation Rules
Core Identification
id	Unique Identifier	The primary internal system ID for the investment.	• Required • System-generated, Read-only
public_id	Text	A user-facing, non-sequential identifier for the investment.	• Required, Unique • System-generated
Key Associations
Fund association	Foreign Key	A reference to the Fund invested in.	• Required
profile_id	Foreign Key	A reference to the Profile making the investment.	• Required
user_id	Foreign Key	A reference to the User who initiated the investment.	• Required
Status & Progress
status	Choice	The overall status of the investment application and its lifecycle.	• Required • Must be one of: NEW, CONFIRMED, LEGALLY_CONFIRMED, CLOSED_SUCCESSFULLY, CLOSED_UNSUCCESSFULLY, CANCELLED_BY_MANAGER, CANCELLED_BY_INVESTOR. See investment status lifecycle.
current_step	Choice	The last completed step in the multi-step investment user flow. Used to allow users to resume.	• Required • Must be one of: SETUP, SIGNATURE, REVIEW
Financial Details
amount	Currency	The total monetary value of the investment.	• Required • Must be a positive number
number_of_shares	Canonical decimal string	The exact number of shares or tokens this investment represents.	• Required • Must be positive • Calculated exactly from amount / price_per_share where applicable • Must match the canonical numeric(38,18) string contract
Funding & Payment Details
funding_method	Choice	The payment method selected by the investor.	• Required • Must be one of: WALLET, CRYPTO WALLET, BANK_ACCOUNT, ACH, WIRE
payment_provider	Choice	The payment provider processing the funds for this investment.	• Required • Must be one of: DWOLLA, NORTH_CAPITAL, EVM
funding_status	Choice	The granular, real-time status of the payment transaction.	• Required • System-managed • Must be one of: new, initialize, in_progress, received, settled, failed, sent_back_pending, sent_back_settled, canceled, creation_error. See Funding Status Lifecycle.
payment_provider_transfer_id	Text	The unique transaction ID from the external payment provider's system.	• System-set
Legal & Timestamps
signature_status	Choice	The status of the e-signature on the investment agreement.	• Required • Must be one of: PENDING, SIGNED
signed_agreement_url	URL	A link to the fully executed, legally binding investment agreement document.	• System-set after signing
submitted_at	Timestamp	The exact date and time the investor completed the final "review" step.	• System-set
created_at	Timestamp	The date and time the investment record was first created.	• Read-only
updated_at	Timestamp	The date and time the investment was last modified.	• Read-only

Key Relationships

• Fund: An Investment belongs to exactly one Fund (a many-to-one relationship) through the fund association field.

• Profile: An Investment is made by exactly one Profile (a many-to-one relationship).

• User: An Investment is owned by one User account (a many-to-one relationship).

• Transactions: An Investment can have one or more Transaction and EVM-Transfer records associated with it, detailing the movement of funds (e.g., payment, refund) (a one-to-many relationship).

Auditing & Event History

The system records significant actions or changes involving an Investment as immutable entries in the system-wide EventLog.

Exact share contract

number_of_shares is stored as PostgreSQL numeric(38,18) and is represented by public APIs, existing v1 domain events, snapshots, notifications, and generated clients as a canonical JSON string. It must match ^(0|[1-9][0-9]{0,19})(\.[0-9]{0,17}[1-9])?$ and must be greater than zero. JSON numeric tokens, signs, leading zeros, exponent notation, excessive precision or scale, and insignificant trailing fractional zeros are rejected; the value is never normalized through binary floating-point arithmetic.