initial commit

README.md

@@ -0,0 +1,93 @@
+# Castle Accounting Extension for LNbits
+
+A full-featured double-entry accounting system for collective projects, integrated with LNbits Lightning payments.
+
+## Overview
+
+Castle Accounting enables collectives like co-living spaces, makerspaces, and community projects to:
+- Track expenses and revenue with proper accounting
+- Manage individual member balances
+- Record contributions as equity or reimbursable expenses
+- Track accounts receivable (what members owe)
+- Generate Lightning invoices for settlements
+
+## Installation
+
+This extension is designed to be installed in the `lnbits/extensions/` directory.
+
+```bash
+cd lnbits/extensions/
+# Copy or clone the castle directory here
+```
+
+Enable the extension through the LNbits admin interface or by adding it to your configuration.
+
+## Usage
+
+### For Members
+
+1. **Add an Expense**: Record money you spent on behalf of the collective
+   - Choose "Liability" if you want reimbursement
+   - Choose "Equity" if it's a contribution
+
+2. **View Your Balance**: See if the Castle owes you money or vice versa
+
+3. **Pay Outstanding Balance**: Generate a Lightning invoice to settle what you owe
+
+### For Admins
+
+1. **Create Accounts Receivable**: Record when someone owes the collective money
+
+2. **Record Revenue**: Track income received by the collective
+
+3. **View All Transactions**: See complete accounting history
+
+4. **Make Payments**: Record payments to members
+
+## Architecture
+
+### Data Models
+
+- **Account**: Individual accounts in the chart of accounts
+- **JournalEntry**: Transaction header with description and date
+- **EntryLine**: Individual debit/credit lines (always balanced)
+
+### Account Types
+
+- **Assets**: Things the Castle owns (Cash, Bank, Accounts Receivable)
+- **Liabilities**: What the Castle owes (Accounts Payable to members)
+- **Equity**: Member contributions and retained earnings
+- **Revenue**: Income streams
+- **Expenses**: Operating costs
+
+### Database Schema
+
+The extension creates three tables:
+- `castle.accounts` - Chart of accounts
+- `castle.journal_entries` - Transaction headers
+- `castle.entry_lines` - Debit/credit lines
+
+## API Reference
+
+See [description.md](description.md) for full API documentation.
+
+## Development
+
+To modify this extension:
+
+1. Edit models in `models.py`
+2. Add database migrations in `migrations.py`
+3. Implement business logic in `crud.py`
+4. Create API endpoints in `views_api.py`
+5. Update UI in `templates/castle/index.html`
+
+## Contributing
+
+Contributions welcome! Please ensure:
+- Journal entries always balance
+- User permissions are properly checked
+- Database transactions are atomic
+
+## License
+
+MIT License - feel free to use and modify for your collective!