Kitledger: A Framework for Transactional Systems

Overview

In a society that has become increasingly more transactional, we need systems that can process operations reliably at scale, while remaining highly auditable and flexible without becoming incomprehensible monoliths.

Kitledger is a generic double-entry framework designed to serve as the foundation for any transactional system that can be modeled through double-entry principles. It provides the core primitives needed to build domain-specific applications without imposing financial or accounting assumptions.

Core Concepts

1. Accounts

• Generic containers that hold balances
• No built-in account types or classifications
• Support for custom metadata and hierarchies
• Identifiable by unique IDs and optional paths

2. Transactions

• Atomic movement of units between accounts
• Strict double-entry enforcement (debits = credits)
• Immutable once committed
• Support for domain-specific metadata

3. Units

• Arbitrary unit types (hours, currency, items, etc.)
• No assumption about what units represent
• Support for unit conversion when applicable

4. Journals

• Chronological record of all transactions
• Append-only design for audit purposes
• Query capabilities for historical analysis

Core Benefits

1. Immutable Audit Trail

   • Every transaction is permanent and traceable
   • Complete history of all system changes
   • Built-in support for compliance and auditing

2. Guaranteed Consistency

   • Double-entry principle ensures balanced transactions
   • Prevents data inconsistencies and reconciliation issues
   • Mathematical verification of system integrity

3. Scalable Performance

   • Optimized for high-throughput transaction processing
   • Efficient querying and reporting
   • Designed for horizontal scaling

4. Flexible Dimensioning

   • Support for custom transaction attributes
   • Multi-dimensional analysis capabilities
   • Consistent reporting structure

Technical Features

• High-performance transaction processing
• REST API and RPC endpoints
• Basic authentication for service-to-service communication
• PostgreSQL storage backend
• Change data capture for OLAP replication
• Designed for sidecar deployment pattern
• Multi-tenancy support

Use Cases

Kitledger Core can be used to build:

• Financial accounting systems
• Project time tracking
• Inventory management
• Energy credit systems
• Loyalty point programs
• Carbon accounting
• Water rights management
• Cloud resource allocation
• Software license management
• Healthcare resource tracking
• Any domain requiring transactional integrity

Deployment

Kitledger is designed to be deployed as a sidecar alongside your application:

• Each application instance gets its dedicated Kitledger instance
• Communication happens via localhost or Unix sockets for optimal performance
• Multiple application+Kitledger pairs can share a single PostgreSQL database
• Scales horizontally by adding more application+Kitledger instances

Getting Started

1. Deploy Kitledger as a sidecar alongside your application
2. Define your account structure via the API
3. Implement your domain-specific business logic in your application
4. Use Kitledger API to record transactions via localhost
5. Query balances and transaction history as needed

Extending Kitledger

Build domain-specific applications on top of Kitledger by:

1. Defining the semantic meaning of accounts in your domain
2. Creating transaction types relevant to your business processes
3. Implementing validation rules specific to your domain
4. Building reporting and analytics for your use case

---

Kitledger Core is the transaction engine - you provide the domain context.