System Architecture
Overview of the Keshless Accounting System structure and component interactions.
Core Principles
| Principle | Description |
|---|---|
| ACID Compliance | All operations use PostgreSQL transactions |
| Immutability | Posted ledger entries cannot be modified |
| Double-Entry | Every transaction creates balanced debit/credit pairs |
Architecture Layers
┌─────────────────────────────────────────────────────┐
│ Application Layer │
│ (Wallet Controllers, Payment APIs, Transactions) │
└─────────────────────────┬───────────────────────────┘
↓
┌─────────────────────────────────────────────────────┐
│ Service Layer │
│ Ledger | Templates | Posting | Balance Verify │
│ Trial Balance | Statement | Chart of Accounts │
└─────────────────────────┬───────────────────────────┘
↓
┌─────────────────────────────────────────────────────┐
│ Data Layer │
│ JournalEntry | LedgerEntry | ChartOfAccounts │
│ AccountBalance | Reconciliation | AuditLog │
└─────────────────────────┬───────────────────────────┘
↓
┌─────────────────────────────────────────────────────┐
│ PostgreSQL Database │
└─────────────────────────────────────────────────────┘Data Models
ChartOfAccounts
Hierarchical account structure.
| Field | Description |
|---|---|
code | Unique account code (e.g., "1110") |
name | Account name |
type | ASSET, LIABILITY, EQUITY, REVENUE, EXPENSE |
normalBalance | DEBIT or CREDIT |
currency | E (Emalageni) |
Account Ranges:
- 1000-1999: Assets
- 2000-2999: Liabilities
- 3000-3999: Equity
- 4000-4999: Revenue
- 5000-5999: Expenses
JournalEntry
Groups related ledger entries for a single transaction.
| Field | Description |
|---|---|
journalId | Unique ID (JE-XXXXXX) |
status | PENDING, POSTED, REVERSED, CANCELLED |
totalAmount | Transaction amount |
walletTransactionId | Link to source transaction |
reversalOf | If reversing another entry |
LedgerEntry
Individual debit or credit records.
| Field | Description |
|---|---|
entryId | Unique ID (LE-XXXXXX) |
journalId | Parent journal |
accountCode | Chart of Accounts reference |
type | DEBIT or CREDIT |
amount | Entry amount |
entityId | User/Vendor reference |
status | PENDING, POSTED, REVERSED |
Immutability: Once status = POSTED, entry cannot be modified.
AccountBalance
Denormalized cache for fast balance queries.
| Field | Description |
|---|---|
accountCode | Account reference |
balance | Current balance |
version | Optimistic locking |
lastReconciledAt | Last reconciliation |
AuditLog
Tamper-proof audit trail with SHA-256 hash chaining.
| Field | Description |
|---|---|
eventType | JOURNAL_CREATED, ENTRY_POSTED, etc. |
changes | Before/after state |
previousHash | Hash of previous entry |
currentHash | SHA-256 hash of this entry |
Hash Chain: Any tampering breaks the chain and is immediately detectable.
Services
ledgerService
Core journal and ledger operations.
| Method | Description |
|---|---|
createJournalEntry() | Create journal with entries |
reverseJournalEntry() | Create reversing entry |
getJournalById() | Retrieve journal |
transactionTemplatesService
Pre-built double-entry transaction patterns.
| Template | Description |
|---|---|
getUserTransferTemplate() | P2P transfers |
getUserPaymentTemplate() | User → Vendor |
getUserTopupTemplate() | Wallet topups |
getUserWithdrawalTemplate() | Cash withdrawals |
getUserRefundTemplate() | Refunds |
getManualAdjustmentTemplate() | Admin corrections |
postingService
Pending → posted workflow management.
| Method | Description |
|---|---|
postEntry() | Manually post entry |
cancelEntry() | Cancel pending entry |
autoPostPendingEntries() | Auto-post old entries |
reviewEntry() | Approve/reject flagged |
balanceVerificationService
Reconciliation and balance verification.
| Method | Description |
|---|---|
verifyUserBalance() | Check user wallet vs ledger |
verifyAllUserBalances() | Reconcile all users |
fixDiscrepancy() | Auto-fix balance issues |
Job Scheduling
dailyReconciliation
Runs at 2 AM daily.
Tasks:
- Auto-post pending entries > 30 minutes old
- Verify all user/vendor balances
- Generate trial balance
- Create reconciliation record
- Alert on discrepancies
Performance Features
| Feature | Benefit |
|---|---|
| Balance Caching | Fast queries via AccountBalance |
| Optimistic Locking | Prevents race conditions |
| Indexed Queries | Critical indexes on all models |
Security Features
| Feature | Protection |
|---|---|
| Immutability | Posted entries locked at DB level |
| Hash Chaining | Tamper detection via SHA-256 |
| Audit Trail | Every action logged |
| Transaction Isolation | PostgreSQL ACID compliance |
| Optimistic Locking | Concurrent update protection |