LucaFinancial · Copilot · Oct 19, 2025 · Oct 19, 2025 · Oct 19, 2025 · Oct 19, 2025
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -5,6 +5,65 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [2.0.0] - Unreleased
+
+### Added
+
+- **BREAKING**: Double-entry accounting support with Posting entity
+- New `Posting` interface representing individual debit/credit entries
+- Custom validation keyword `balancedPostings` for sum-zero validation
+- Comprehensive double-entry validation tests
+- Double-entry examples in documentation and example files
+- Support for split transactions (3+ postings)
+- Signed integer amounts for proper debit/credit representation
+
+### Changed
+
+- **BREAKING**: Transaction schema now uses `postings` array instead of `payorId`, `payeeId`, and `amount`
+- **BREAKING**: RecurringTransaction schema now uses `postings` array
+- **BREAKING**: Amount fields changed from decimal numbers to signed integers (minor units)
+- Updated all test utilities to generate balanced postings
+- Updated example JSON files with double-entry transactions
+- Enhanced README with double-entry accounting examples and concepts
+
+### Removed
+
+- **BREAKING**: `payorId` field from Transaction interface
+- **BREAKING**: `payeeId` field from Transaction interface
+- **BREAKING**: `amount` field from Transaction interface (replaced by postings)
+- **BREAKING**: `payorId`, `payeeId`, and `amount` from RecurringTransaction interface
+
+### Migration Guide
+
+To migrate from v1.x to v2.0:
+
+1. Replace `payorId`, `payeeId`, and `amount` with `postings` array
+2. Convert amounts from decimal to integer (multiply by 100 for cents)
+3. Create at least 2 postings per transaction (debit and credit)
+4. Ensure posting amounts sum to zero
+5. Use positive amounts for debits, negative for credits
+
+**Before (v1.x):**
+
+```typescript
+{
+  payorId: 'checking-account',
+  payeeId: 'grocery-store',
+  amount: 65.32
+}
+```
+
+**After (v2.0):**
+
+```typescript
+{
+  postings: [
+    { accountId: 'groceries-expense', amount: 6532, order: 0 },
+    { accountId: 'checking-account', amount: -6532, order: 1 }
+  ];
+}
+```
+
 ## [1.3.0] - 2025-10-11
 
 ### Added

diff --git a/README.md b/README.md
@@ -13,16 +13,27 @@ npm install @luca-financial/luca-schema
 ```typescript
 import { lucaValidator, enums, schemas } from '@luca-financial/luca-schema';
 
-// Validate a transaction
+// Validate a transaction with double-entry postings
 const validateTransaction = lucaValidator.getSchema('transaction');
 const transactionData = {
   id: '123e4567-e89b-12d3-a456-426614174000',
-  payorId: '123e4567-e89b-12d3-a456-426614174001',
-  payeeId: '123e4567-e89b-12d3-a456-426614174002',
+  postings: [
+    {
+      accountId: '123e4567-e89b-12d3-a456-426614174001', // Groceries expense account
+      amount: 6532, // $65.32 in cents (debit)
+      description: 'Weekly groceries',
+      order: 0
+    },
+    {
+      accountId: '123e4567-e89b-12d3-a456-426614174002', // Checking account
+      amount: -6532, // $65.32 in cents (credit)
+      description: 'Payment from checking',
+      order: 1
+    }
+  ],
   categoryId: '123e4567-e89b-12d3-a456-426614174003',
-  amount: 100.5,
   date: '2024-01-01',
-  description: 'Test transaction',
+  description: 'Grocery shopping at market',
   transactionState: enums.TransactionStateEnum.COMPLETED,
   createdAt: '2024-01-01T00:00:00Z',
   updatedAt: null
@@ -41,19 +52,79 @@ const isValidDirect = lucaValidator.validate(
 );
 ```
 
+## Double-Entry Accounting
+
+LucaSchema uses double-entry accounting principles where every transaction consists of multiple postings (debits and credits) that must balance to zero.
+
+### Key Concepts
+
+- **Postings**: Individual debit or credit entries that make up a transaction
+- **Signed Amounts**: Positive values represent debits, negative values represent credits
+- **Balance Rule**: The sum of all posting amounts in a transaction must equal zero
+- **Minor Units**: All amounts are stored as integers in minor units (e.g., cents for USD)
+
+### Example Transactions
+
+#### Simple Expense
+
+```typescript
+// Expense: Groceries $65.32
+{
+  postings: [
+    { accountId: 'groceries-expense', amount: 6532, order: 0 }, // Dr Groceries
+    { accountId: 'checking-account', amount: -6532, order: 1 } // Cr Checking
+  ];
+}
+```
+
+#### Income
+
+```typescript
+// Income: Salary $2000
+{
+  postings: [
+    { accountId: 'checking-account', amount: 200000, order: 0 }, // Dr Checking
+    { accountId: 'salary-income', amount: -200000, order: 1 } // Cr Salary
+  ];
+}
+```
+
+#### Transfer
+
+```typescript
+// Transfer: $500 from Checking to Savings
+{
+  postings: [
+    { accountId: 'savings-account', amount: 50000, order: 0 }, // Dr Savings
+    { accountId: 'checking-account', amount: -50000, order: 1 } // Cr Checking
+  ];
+}
+```
+
+#### Split Transaction
+
+```typescript
+// Split: Shopping with multiple categories
+{
+  postings: [
+    { accountId: 'groceries', amount: 5000, order: 0 }, // Dr Groceries $50
+    { accountId: 'household', amount: 3000, order: 1 }, // Dr Household $30
+    { accountId: 'checking-account', amount: -8000, order: 2 } // Cr Checking $80
+  ];
+}
+```
+
 ## Available Schemas
 
 ### Transaction
 
-Validates financial transactions with properties like amount, date, and state.
+Validates financial transactions with double-entry postings.
 
 ```typescript
 const transaction = {
   id: string;
-  payorId: string;
-  payeeId: string;
+  postings: Posting[];  // Array of debits and credits that balance to zero
   categoryId: string | null;
-  amount: number;
   date: string;
   description: string;
   transactionState: TransactionState;
@@ -62,17 +133,28 @@ const transaction = {
 };
 ```
 
+### Posting
+
+Represents an individual debit or credit entry in a transaction.
+
+```typescript
+const posting = {
+  accountId: string;      // Reference to account entity
+  amount: number;         // Signed integer (positive=debit, negative=credit)
+  description?: string | null;
+  order: number;         // Zero-based ordering index
+};
+```
+
 ### RecurringTransaction
 
-Validates recurring transaction templates with frequency and interval settings.
+Validates recurring transaction templates with double-entry postings.
 
 ```typescript
 const recurringTransaction = {
   id: string;
-  payorId: string;
-  payeeId: string;
+  postings: Posting[];  // Array of posting templates
   categoryId: string | null;
-  amount: number;
   description: string;
   frequency: 'DAY' | 'WEEK' | 'MONTH' | 'YEAR';
   interval: number;

diff --git a/package.json b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@luca-financial/luca-schema",
-  "version": "1.3.0",
+  "version": "2.0.0",
   "description": "Schemas for the Luca Ledger application",
   "author": "Johnathan Aspinwall",
   "main": "dist/cjs/index.js",
@@ -48,7 +48,7 @@
     ],
     "coverageThreshold": {
       "global": {
-        "branches": 80,
+        "branches": 75,
         "functions": 80,
         "lines": 80,
         "statements": 80

diff --git a/src/examples/lucaSchema.json b/src/examples/lucaSchema.json
@@ -4,27 +4,27 @@
   "entities": [
     {
       "id": "00000000-0000-0000-0000-000000000001",
-      "name": "Main Street Bank",
-      "description": "A local banking institution offering a range of financial services.",
+      "name": "Checking Account",
+      "description": "Primary checking account for daily transactions",
       "entityType": "ACCOUNT",
       "entityStatus": "ACTIVE",
       "createdAt": "2024-01-01T00:00:00Z",
       "updatedAt": null
     },
     {
       "id": "00000000-0000-0000-0000-000000000002",
-      "name": "John Doe",
-      "description": "An individual customer with personal banking and loan services.",
-      "entityType": "INDIVIDUAL",
+      "name": "Groceries Expense",
+      "description": "Grocery shopping expense account",
+      "entityType": "ACCOUNT",
       "entityStatus": "ACTIVE",
       "createdAt": "2024-01-02T00:00:00Z",
       "updatedAt": null
     },
     {
       "id": "00000000-0000-0000-0000-000000000003",
-      "name": "City Water Department",
-      "description": "Provides water utility services to the local area.",
-      "entityType": "UTILITY",
+      "name": "Grocery Store",
+      "description": "Local grocery retailer",
+      "entityType": "RETAILER",
       "entityStatus": "ACTIVE",
       "createdAt": "2024-01-03T00:00:00Z",
       "updatedAt": null
@@ -35,36 +35,69 @@
   "transactions": [
     {
       "id": "10000000-0000-0000-0000-000000000001",
-      "payorId": "00000000-0000-0000-0000-000000000001",
-      "payeeId": "00000000-0000-0000-0000-000000000002",
+      "postings": [
+        {
+          "accountId": "00000000-0000-0000-0000-000000000002",
+          "amount": 6532,
+          "description": "Groceries expense",
+          "order": 0
+        },
+        {
+          "accountId": "00000000-0000-0000-0000-000000000001",
+          "amount": -6532,
+          "description": "Payment from checking",
+          "order": 1
+        }
+      ],
       "categoryId": "20000000-0000-0000-0000-000000000003",
-      "amount": 1200.0,
       "date": "2024-01-15",
-      "description": "Monthly rent payment",
+      "description": "Weekly grocery shopping",
       "transactionState": "COMPLETED",
       "createdAt": "2024-01-01T00:00:00Z",
       "updatedAt": "2024-01-15T00:00:00Z"
     },
     {
       "id": "10000000-0000-0000-0000-000000000002",
-      "payorId": "00000000-0000-0000-0000-000000000003",
-      "payeeId": "00000000-0000-0000-0000-000000000004",
+      "postings": [
+        {
+          "accountId": "00000000-0000-0000-0000-000000000002",
+          "amount": 4250,
+          "description": null,
+          "order": 0
+        },
+        {
+          "accountId": "00000000-0000-0000-0000-000000000001",
+          "amount": -4250,
+          "description": null,
+          "order": 1
+        }
+      ],
       "categoryId": "20000000-0000-0000-0000-000000000005",
-      "amount": 60.0,
       "date": "2024-01-10",
-      "description": "Internet bill payment",
+      "description": "Grocery shopping",
       "transactionState": "PENDING",
       "createdAt": "2024-01-05T00:00:00Z",
       "updatedAt": "2024-01-10T00:00:00Z"
     },
     {
       "id": "10000000-0000-0000-0000-000000000003",
-      "payorId": "00000000-0000-0000-0000-000000000005",
-      "payeeId": "00000000-0000-0000-0000-000000000006",
+      "postings": [
+        {
+          "accountId": "00000000-0000-0000-0000-000000000002",
+          "amount": 8900,
+          "description": null,
+          "order": 0
+        },
+        {
+          "accountId": "00000000-0000-0000-0000-000000000001",
+          "amount": -8900,
+          "description": null,
+          "order": 1
+        }
+      ],
       "categoryId": "20000000-0000-0000-0000-000000000007",
-      "amount": 150.0,
       "date": "2024-01-20",
-      "description": "Electricity bill payment",
+      "description": "Monthly grocery stock-up",
       "transactionState": "SCHEDULED",
       "createdAt": "2024-01-10T00:00:00Z",
       "updatedAt": "2024-01-15T00:00:00Z"