castle/description.md

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.