Data Model: Investment
Purpose: The Investment entity is a transactional record that represents a single investor's financial commitment to a specific Offer. It acts as the central hub for linking a Profile to an Offer, tracking the investment amount, the status of the legal documentation, and the complete lifecycle of the funding process.
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 | |||
offer_id | Foreign Key | A reference to the Offer 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 |
shares_purchased | Integer | The number of shares or tokens this investment represents. | • Read-only • Calculated: amount / Offer.price_per_share |
| 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: INITIALIZED, IN_PROGRESS, RECEIVED, SETTLED, CANCELLED, FAILED, etc. |
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
Offer: An
Investmentbelongs to exactly one Offer (a many-to-one relationship).Profile: An
Investmentis made by exactly one Profile (a many-to-one relationship).User: An
Investmentis owned by one User account (a many-to-one relationship).Transactions: An
Investmentcan 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
Every significant action or change made to an Investment is recorded as an immutable entry in a system-wide EventLog. This creates a complete and tamper-proof audit trail for compliance and operational tracking.