Bitcoin Kampala Tracker

A Frappe application for tracking Bitcoin donations (inflows) and Ugandan Shilling expenses (outflows) for the Bitcoin Kampala community.

Features

• Transaction Management: Track both inflows (donations, grants, sponsorships) and outflows (expenses, payments)
• Multi-Currency Support: UGX, USD, BTC, and SATS with automatic conversion
• Budget Tracking: Set spending limits by category with alerts when nearing/exceeding budgets
• Receipt Management: Attach and organize receipts and proof documents
• Dashboard: Visual overview with charts and quick actions
• Google Sheets Sync: Optional backup/sync to Google Sheets
• BTCPay Integration: Auto-import Bitcoin donations from BTCPay Server
• Role-Based Access: Admin, Accountant, and Viewer roles with granular permissions

Security Features

• Encrypted Secrets: All API keys and sensitive credentials stored using Frappe's Password field type (encrypted at rest)
• Role-Based Permissions: Granular access control for different user types
• Audit Trail: Full tracking of all changes via Frappe's track_changes
• HTTPS Only: All external API calls enforce HTTPS connections
• Input Validation: All user inputs sanitized to prevent XSS and injection attacks
• Submittable Transactions: Optional approval workflow for financial transactions

Installation

Prerequisites

• Frappe Bench (v15+)
• Python 3.10+
• MariaDB or PostgreSQL

Install via Bench

# Navigate to your bench directory
cd frappe-bench

# Get the app
bench get-app https://github.com/bitcoinkampala/bitcoin_kampala_tracker

# Install on your site
bench --site your-site.local install-app bitcoin_kampala_tracker

# Run migrations
bench --site your-site.local migrate

Post-Installation Setup

1. Configure Settings: Go to BKT Settings and configure:

   • Organization name
   • Exchange rates (USD/UGX, BTC/USD)
   • Google Sheets integration (optional)
   • BTCPay Server integration (optional)

2. Assign Roles: Assign users to appropriate roles:

   • BKT Admin: Full access to all features
   • BKT Accountant: Can create and edit transactions
   • BKT Viewer: Read-only access

3. Review Categories: Default categories are created automatically. Add or modify as needed.

DocTypes

DocType	Description
BKT Settings	App configuration (Single DocType)
BKT Transaction	Financial transactions
BKT Transaction Category	Categories for inflows/outflows
BKT Wallet	Bitcoin wallets for tracking inflow sources
BKT Budget	Budget definitions and tracking
BKT Transaction Attachment	Child table for receipts

API Endpoints

Transaction APIs

• create_transaction: Create a new transaction
• bulk_create_transactions: Create multiple transactions (Admin only)
• get_transactions_for_export: Export transactions to JSON/CSV
• get_transaction_summary: Get inflow/outflow totals
• get_category_breakdown: Get spending by category
• get_monthly_trends: Get monthly transaction trends

Budget APIs

• get_budget_status: Get all budget statuses
• get_budget_alerts: Get budgets near/over limit
• check_budget_before_expense: Check if expense would exceed budget

Sync APIs

• sync_to_google_sheets: Sync transactions to Google Sheets
• fetch_btcpay_transactions: Import from BTCPay Server
• fetch_exchange_rates: Update BTC/USD exchange rate
• upload_receipt_to_drive: Upload receipt to Google Drive

Roles & Permissions

Role	Read	Create	Write	Delete	Submit	Cancel
BKT Admin	✓	✓	✓	✓	✓	✓
BKT Accountant	✓	✓	✓	-	-	-
BKT Viewer	✓	-	-	-	-	-

Default Categories

Inflows

• Donation, Grant, Sponsorship, Personal Contribution, Event Revenue, Other Income

Outflows

• Fruits Program, Orphanage Support, Equipment, Travel, Rent, Events, Education, Teachers Pay, Internet & Utilities, Personal Expenses, Other Expense

Default Wallets

• Blink (Custodial)
• Wallet of Satoshi (Lightning)
• Machankura (Lightning)
• Onchain - Blink (Onchain)
• Cash (Other)

Development

Running Tests

bench --site your-site.local run-tests --app bitcoin_kampala_tracker

Building Assets

bench build --app bitcoin_kampala_tracker

License

MIT License

Contributing

Contributions are welcome! Please submit pull requests to the repository.

Support

For issues and feature requests, please use the GitHub issue tracker.

---

Made with ₿ by Bitcoin Kampala