Data Model: Transaction

Purpose: The Transaction entity represents a single, immutable financial event within the platform's wallet ecosystem. Each record acts as a permanent ledger entry, tracking the movement of funds for a specific purpose, such as an investment, deposit, or distribution. Once created, a transaction cannot be altered, ensuring a complete and auditable financial history.

Fields/Attributes

Name	Type	Description	Validation Rules
Core Identification
id	Unique Identifier	The primary internal system ID for the transaction.	• Required • System-generated, Read-only
Financial Details
amount	Currency	The monetary value of the transaction.	• Required • Must be a positive number
type	Choice	The business purpose of the transaction. This determines how wallet balances are affected.	• Required • Must be one of: DEPOSIT, WITHDRAWAL, INVESTMENT, DISTRIBUTION
description	Text	A human-readable memo describing the transaction and mentioning source and destination accounts.	• Required • System-generated
Status & Timestamps
status	Choice	The current state of the transaction.	• Required • Must be one of: PENDING, PROCESSED, FAILED, CANCELLED
created_at	Timestamp	The date and time the transaction was initiated.	• Read-only
completed_at	Timestamp	The date and time the transaction was successfully settled or failed.	• Read-only
Associations & Context
source_wallet_id	Foreign Key	A reference to the Wallet from which funds were debited.	• Required • System-generated
destination_wallet_id	Foreign Key	A reference to the Wallet to which funds were credited.	• Required • System-generated
investment_id	Foreign Key	A reference to the Investment that this transaction is associated with.	• Nullable
provider_transaction_id	Text	The unique transaction ID from the external payment provider's system (e.g., Dwolla).	• Optional

Key Relationships

• Wallet: A Transaction is fundamentally linked to one or two Wallets . Many transactions can be associated with a single wallet (a many-to-one relationship).

• Investment: An Investment can be associated with one or more Transactions (e.g., the initial payment and a potential future refund) (a one-to-many relationship).

Global Business Rules

• Immutability: A Transaction record, once its status is PROCESSED or FAILED, is immutable. It cannot be edited or deleted. To reverse a transaction, a new, opposing transaction (e.g., a REFUND) must be created. This is critical for maintaining a perfect audit trail.

• Balance Checks: Before creating a WITHDRAWAL or INVESTMENT transaction, the system must verify that the source_wallet has a sufficient available balance (balance - outcoming_balance).

• Atomic Operations: The creation of a Transaction and the corresponding updates to the source_wallet and destination_wallet balances must be an atomic operation. If any part of the process fails, the entire operation must be rolled back to prevent data inconsistency.

• Cancellable Transactions: A Transaction of type DEPOSIT or WITHDRAWAL can be cancelled by the user or an admin, but only while its status is PENDING. Once it is COMPLETED or FAILED, it is immutable.

Auditing & Event History

Every significant action or change made to an Transaction 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.