jchristn77/netledger-ui repository overview

⁠NetLedger

NetLedger is a thread-safe, self-contained ledgering library for .NET 8.0 that provides rigorous financial transaction control with full audit trails. Built on SQLite with async/await throughout, it enables strict separation between pending and committed transactions, making it ideal for applications requiring precise financial controls and auditability.

⁠Who Should Use NetLedger

NetLedger is designed for developers building applications that require:

• Strict Financial Controls - Separate pending and committed transaction states with explicit commit operations
• Full Audit Trails - Immutable transaction history with balance chains for forensic accounting
• Thread Safety - Account-level locking ensures safe concurrent access without race conditions
• Embedded Storage - Self-contained SQLite database with no external dependencies
• Transactional Integrity - ACID-compliant operations with atomic commits and rollback on failure
• Async/Await Support - Modern .NET async patterns with cancellation token support throughout

Ideal use cases: Financial applications, expense tracking systems, point-of-sale systems, accounting software, multi-user financial platforms, billing systems, payment processing, and any application requiring double-entry bookkeeping.

⁠What NetLedger Does

⁠Core Capabilities

• ✅ Account Management - Create, retrieve, search, and delete accounts with optional initial balances
• ✅ Transaction Operations - Add credits and debits as pending or immediately committed
• ✅ Batch Operations - Process multiple credits or debits in a single atomic operation
• ✅ Dual Balance Tracking - Separate committed balance (finalized) and pending balance (projected)
• ✅ Selective Commits - Commit all pending entries or specific entries by GUID
• ✅ Entry Cancellation - Cancel pending entries before commit
• ✅ Transaction History - Query entries with filtering by date range, amount range, and ordering
• ✅ Pagination Support - Continuation token-based enumeration for large datasets (up to 1000 records per query)
• ✅ Point-in-Time Balances - Calculate balances as of any historical timestamp
• ✅ Balance Chain Verification - Validate audit trail integrity across all balance entries
• ✅ Event Notifications - Async events for all state changes (account created/deleted, entries added/committed/canceled)
• ✅ Thread-Safe Operations - SemaphoreSlim-based account locking prevents concurrent modification issues
• ✅ Connection Pooling - High-performance connection pool (max 500 connections, 120s timeout)

⁠What NetLedger Does NOT Do

• ❌ Multi-Currency Support - Single currency per ledger (implement multiple ledgers for multi-currency)
• ❌ Automatic Transfers - No built-in inter-account transfers (manually debit one account and credit another)
• ❌ Authentication/Authorization - No user management or permissions (implement at application level)
• ❌ Multi-Tenant Isolation - Single database instance (use separate databases for tenants)
• ❌ External Databases - SQLite only (contact maintainer for external database support)
• ❌ Transaction Reversal - Cannot undo committed entries (create offsetting entries instead)
• ❌ Scheduled Transactions - No recurring or future-dated entries
• ❌ Account Hierarchies - No parent-child account relationships
• ❌ Budget Enforcement - No built-in spending limits or budget tracking
• ❌ Custom Fields - Fixed schema for accounts and entries

⁠License

MIT License - See LICENSE.md⁠ for details

⁠Contributing

Contributions are welcome! Please see CONTRIBUTING.md⁠ for guidelines.

⁠Support

• Issues: GitHub Issues⁠
• Discussions: GitHub Discussions⁠
• NuGet Package: NetLedger on NuGet⁠

⁠Version History

⁠v2.0.0 (Current)

• Full async/await support throughout
• Transaction support with ACID guarantees
• Batch operations for credits and debits
• Enhanced error handling with specific exception types
• Performance improvements with connection pooling
• Breaking changes from v1.x (see CHANGELOG.md⁠)

See CHANGELOG.md⁠ for complete version history.