initial commit

description.md

@@ -0,0 +1,65 @@
+# Castle Accounting
+
+A comprehensive double-entry accounting system for collective projects, designed specifically for LNbits.
+
+## Features
+
+- **Double-Entry Bookkeeping**: Full accounting system with debits and credits
+- **Chart of Accounts**: Pre-configured accounts for Assets, Liabilities, Equity, Revenue, and Expenses
+- **User Expense Tracking**: Members can record out-of-pocket expenses as either:
+  - **Liabilities**: Castle owes them money (reimbursable)
+  - **Equity**: Their contribution to the collective
+- **Accounts Receivable**: Track what users owe the Castle (e.g., accommodation fees)
+- **Revenue Tracking**: Record revenue received by the collective
+- **User Balance Dashboard**: Each user sees their balance with the Castle
+- **Lightning Integration**: Generate invoices for outstanding balances
+- **Transaction History**: View all accounting entries and transactions
+
+## Use Cases
+
+### 1. User Pays Expense Out of Pocket
+When a member buys supplies for the Castle:
+- They can choose to be reimbursed (Liability)
+- Or contribute it as equity (Equity)
+
+### 2. Accounts Receivable
+When someone stays at the Castle and owes money:
+- Admin creates an AR entry (e.g., "5 nights @ 10€/night = 50€")
+- User sees they owe 50€ in their dashboard
+- They can generate an invoice to pay it off
+
+### 3. Revenue Recording
+When the Castle receives revenue:
+- Record revenue with the payment method (Cash, Lightning, Bank)
+- Properly categorized in the accounting system
+
+## Technical Details
+
+- Built on PostgreSQL/SQLite with full transaction support
+- RESTful API for all operations
+- Validates that journal entries balance before saving
+- Automatic user-specific account creation
+- Indexed for performance on large datasets
+
+## API Endpoints
+
+### User Endpoints (Invoice Key)
+- `GET /api/v1/balance` - Get your balance
+- `POST /api/v1/entries/expense` - Add an expense
+- `GET /api/v1/entries/user` - Get your transactions
+- `POST /api/v1/pay-balance` - Record a payment
+
+### Admin Endpoints (Admin Key)
+- `POST /api/v1/entries/receivable` - Create accounts receivable
+- `POST /api/v1/entries/revenue` - Record revenue
+- `POST /api/v1/pay-user` - Pay a user
+- `POST /api/v1/accounts` - Create new accounts
+- `GET /api/v1/entries` - View all entries
+
+## Getting Started
+
+1. Enable the Castle extension in LNbits
+2. Visit the Castle page to see your dashboard
+3. Start tracking expenses and balances!
+
+The extension automatically creates a default chart of accounts on first run.