Technical docs
Transaction System
How money movements become accounting records. You do not need to be an accountant to understand this.
The Big Picture
User creates a Transaction → System derives Events → Events get reviewed → Approved Events create Journal Entries → Journal lines hit GL accounts.
Core Concepts
Three entities handle different concerns. Users think in transactions, the system creates events, accountants see journals.
| Concept | What It Is | Example | Who Sees It |
|---|---|---|---|
| Transaction | What the user did | "Received $500 from Acme Corp" | Users |
| Event | What it means to accounting | "Sale recorded for $500" | System |
| Journal Entry | The accounting record | "Dr Bank $500, Cr Revenue $500" | Accountants |
Why This Separation?
- Users think in transactions: "I got paid" not "debit cash, credit revenue"
- System needs events: One transaction might create multiple accounting entries
- Accountants need journals: Proper double-entry records for compliance
Transaction Lifecycle
Every transaction follows this state machine from creation to posting.
Key Services
TransactionService- Creates transactionsEventBuilder- Derives events from intentTransactionReviewService- Evaluates completenessJournalGenerationService- Creates journal entries
State Transitions
- Created → EventsBuilt: Automatic via EventBuilder
- EventsBuilt → Review: Automatic evaluation
- Review → Approved: All checks pass or overridden
- Approved → Posted: Journal entry created
Transaction Intents
The Intent field determines what events are created from a transaction.
| Intent | Events Created | Typical Use Case |
|---|---|---|
CUSTOMER_PAYMENT_RECEIVED | Sale, Cash Receipt | Customer pays for goods/services |
SUPPLIER_PAYMENT_MADE | Expense, Cash Disbursement | Paying a vendor |
TRANSFER | Cash Movement | Moving money between accounts |
INVOICE_SETTLEMENT | AR Settlement | Customer pays existing invoice |
BILL_SETTLEMENT | AP Settlement | Paying an existing bill |
OWNER_CONTRIBUTION | Equity Increase | Owner puts money in |
OWNER_WITHDRAWAL | Equity Decrease | Owner takes money out |
REFUND_ISSUED | Contra-Revenue | Refunding a customer |
REFUND_RECEIVED | Contra-Expense | Receiving refund from vendor |
Service Architecture
The accounting engine is composed of focused services that collaborate through the transaction lifecycle.
| Service | Responsibility |
|---|---|
TransactionService | Creates/updates transactions, orchestrates event derivation |
EventBuilder | Builds events from transaction based on Intent |
TransactionReviewService | Evaluates events, applies review flags |
PostingPolicyService | Manages posting rules, CRUD for policies |
JournalGenerationService | Creates journal entries from approved events |
CategoryService | CRUD for transaction categories |
AuditService | Records all changes for audit trail |