README_EN.md

BeeCount

Your Data, Your Control - Open Source Accounting App

Core Advantage: Self-hosted Supabase/WebDAV servers - Your data, Your control

📖 Documentation | 💝 Donate | 💬 Telegram Group | 🇨🇳 中文

---

🎉 Great News

🍎 iOS Version Now Available on App Store!

Search for "BeeCount" on the App Store to download and install

---

🚀 Alipay/WeChat Auto-Billing - Zero Manual Input!

📸 Photo Recognition - AI auto-extracts amount, merchant, and category (Local Model in training + GLM Cloud Model)

⚡ Screenshot Billing - Android screenshot monitoring + iOS Shortcuts, auto-create bills after payment

---

🎨 Recruiting Designers

We're looking for talented UI/UX designers to join the BeeCount project!

📐 What You'll Work On:

• Redesign app UI and interaction experience
• Create theme skins and illustration elements
• Optimize visual consistency across the interface
• Develop a modern, clean design language

🎁 What You'll Get:

• Portfolio pieces for open-source work
• Credit in README and app
• Close collaboration with dev team
• Satisfaction of creating great UX for thousands of users

💌 Contact:

• GitHub Issues: Submit design proposals
• Telegram Group: Join discussion

---

📱 Platform Support

🤖 Android - Download APK | Supports Android 5.0+

🍎 iOS - App Store | TestFlight Beta | Supports iOS 15.5+

📱 HarmonyOS - Coming Soon | Supports HarmonyOS 5.0+ | HarmonyOS Repository

---

💡 Why Choose BeeCount?

🔒 Problems with Traditional Apps ❌ Data stored on third-party servers ❌ Privacy risks, data may be analyzed ❌ Data loss if service shuts down ❌ Premium features behind paywalls ❌ Forced ads and loan recommendations ❌ Closed-source, cannot audit code

✅ BeeCount Advantages ✅ Self-hosted, complete data control ✅ Open source, auditable code ✅ Offline-first, works without network ✅ Free for personal use, no ads or paywalls (including core features like auto-billing) ✅ Privacy-first, developers cannot access your data ✅ Open source code, auditable codebase

A lightweight, open-source, privacy-focused personal finance management and expense tracker app for iOS/Android. Features complete ledger management, income and expense tracking, screenshot auto-billing, category statistics, chart analysis, data import/export, and self-hosted Supabase/WebDAV cloud sync. Perfect for privacy-conscious individuals and families to manage daily spending and budget tracking.

📱 Core Features Showcase

📸 View More Screenshots

Data Management

Personalization & Management

Data Import & Export

🌟 Key Features

☁️ Self-Hosted Cloud Service - Core Differentiator

This is BeeCount's biggest feature: Complete control over your data!

Solution	Best For	Features
Supabase	Users without NAS	Free tier sufficient, easy setup, cloud-hosted
WebDAV	Users with NAS	Fully localized data, supports Synology/UGREEN/Nextcloud

Why Self-Hosted?

• 🔐 Privacy First: Developers cannot access your data
• 💰 Cost Effective: Supabase free tier sufficient, WebDAV one-time investment
• 🛡️ Data Security: No worries about service shutdowns or data breaches
• 🔓 Open Source: All cloud sync code is open source and auditable

📖 View Cloud Service Setup Guide

🔒 Data Security & Privacy

• Offline First: Based on local SQLite, works without network
• Open & Transparent: Open source code, auditable
• Optional Sync: Works completely without cloud configuration
• Zero Tracking: No analytics, no ads, no data collection

🤖 Smart Auto-Billing - One-Tap Payment Recording

🌟 Core Feature Highlight: Screenshot and bill automatically, payment info auto-recognized!

Android Auto-Billing:

• 📸 Accessibility Service Auto-Billing: Once enabled, automatically recognizes payment info and creates bills with each screenshot
• 🎯 Smart Recognition: Auto-recognizes Alipay, WeChat Pay, UnionPay and other mainstream payment methods
• ⚡ Real-time Recording: Screenshot after payment, transaction info recorded immediately

iOS Auto-Billing:

• 🔗 Shortcuts Integration: Automate through iOS "Shortcuts" app
• 👆 Double Tap Back Trigger: After setup, double tap phone back during payment for auto-billing
• 🎨 Flexible Configuration: Supports auto-trigger on screenshot or manual trigger, adapts to different usage scenarios

📊 Complete Accounting Features

• Smart Accounting: Income/expense categories, amounts, dates, notes
• OCR Scan Billing: Take photos or select payment screenshots, auto-recognize amounts and merchant info
• Multi-Ledger Management: Separate management for personal, work, investment
• Independent Account Management: Support for cash, bank cards, credit cards and other account types, each account tracks balance independently
• Account Transfer Feature: Support inter-account transfer records, auto-update balances for both accounts
• Hierarchical Category System: Support parent-child category levels for more detailed transaction classification (choose between flat or hierarchical mode)
• Chart Analysis: Monthly reports, category rankings, trend analysis
• Data Import/Export: CSV format, compatible with mainstream apps
• Home Screen Widgets: iOS/Android widgets for quick overview of income and expenses

🎨 Personalization & Internationalization

• Theme Customization: Multiple theme colors for personalized style
• 3 Languages: Simplified Chinese, Traditional Chinese, English
  • Complete UI translation + smart category mapping
  • Localized date/number formats
  • CSV import auto-recognizes multi-language categories

💡 Want to add a new language? Welcome to create an Issue!

📖 User Guide

Basic Operations

• Add Transaction: Tap the "+" button at the bottom of the home screen
• Edit Record: Tap any transaction record to enter edit page
• Delete Record: Long press transaction record to select delete
• Switch Months: Tap the date at the top or scroll up/down in the list to flip pages
• Hide Amounts: Tap the eye icon in the top right of the home screen

Data Management

• Import Data: Profile → Import Data → Select CSV file
• Export Backup: Profile → Export Data → Select export format
• Category Management: Profile → Category Management → Add/Edit/Delete categories
• Ledger Switching: Bottom navigation → Ledgers → Select or create new ledger

☁️ Cloud Backup Configuration (Optional)

Why Choose Self-Hosted Cloud Service?

• Data Sovereignty: Data completely stored in servers or cloud platforms you control
• Privacy Protection: Developers cannot access any of your data
• Cost Control: Most solutions offer free tiers or one-time purchase options
• Stable & Reliable: No dependency on third-party hosting services, full control
• Flexible Choice: Choose the most suitable solution based on your needs

Option 1: Custom Supabase (Recommended for Beginners)

Use Case: Suitable for users without NAS devices who want to get started quickly

Configuration Steps:

1. Create Supabase Project

   • Visit supabase.com to register an account
   • Create a new project, select appropriate region
   • Get URL and anon key from project settings

2. Configure Storage

   • Create a Storage Bucket named beecount-backups in Supabase console
   • Set as Private (uncheck Public bucket)
   • Configure RLS Access Policies: Create 4 policies to ensure users can only access their own data
     • Go to the bucket's Policies tab
     • Create the following 4 policies (each with the same configuration):
       • SELECT: Allow users to read their own backup files
       • INSERT: Allow users to create new backup files
       • UPDATE: Allow users to update their own backup files
       • DELETE: Allow users to delete their own backup files
     • Configuration for each policy:

       • Policy name: Customizable (e.g., Allow user access to own backups)

       • Target roles: Select authenticated

       • Policy definition: Enter the following expression

         ((bucket_id = 'beecount-backups'::text) AND ((storage.foldername(name))[1] = 'users'::text) AND ((storage.foldername(name))[2] = (auth.uid())::text))

       • This policy ensures users can only access files under beecount-backups/users/<their-user-id>/ path

3. App Configuration

   • Open BeeCount → Profile → Cloud Service
   • Tap "Add Custom Cloud Service"
   • Select service type: Supabase
   • Enter your Supabase URL and anon key
   • Save and enable configuration
   • Tap "Login", register/sign in and start syncing

Option 2: WebDAV Server (Recommended for NAS Users)

Use Case: For users with NAS devices or private cloud storage

Supported Services:

• ✅ UGREEN Cloud NAS
• ✅ Synology NAS
• ✅ Nextcloud
• ✅ Nutstore WebDAV
• ✅ ownCloud
• ✅ Any server supporting WebDAV protocol

Configuration Steps:

1. Enable WebDAV Service

   • Enable WebDAV functionality on your NAS or cloud storage platform
   • Note the WebDAV server address (e.g., http://nas.local:5005)
   • Create or use existing user account

2. Prepare Storage Directory (Optional)

   • Create a BeeCount folder in WebDAV root directory
   • Or use any path (specify during configuration)

3. App Configuration

   • Open BeeCount → Profile → Cloud Service
   • Tap "Add Custom Cloud Service"
   • Select service type: WebDAV
   • Fill in configuration:
     • WebDAV Server URL: e.g., http://nas.local:5005
     • Username: Your WebDAV username
     • Password: Your WebDAV password
     • Remote Path: Storage path (e.g., /home/BeeCount or /BeeCount)
   • Tap "Test Connection" to verify configuration
   • Save and enable configuration
   • WebDAV requires no additional login, can sync directly after configuration

Common WebDAV Configuration Examples:

UGREEN Cloud NAS:
- URL: http://your-nas-address:5005
- Remote Path: /home/BeeCount

Synology NAS:
- URL: http://your-nas-address:5005 or https://your-domain
- Remote Path: /BeeCount

Nutstore:
- URL: https://dav.jianguoyun.com/dav/
- Remote Path: /BeeCount

Future Plans

We will continue expanding cloud service support, planning to add:

• 📦 Alibaba Cloud OSS
• 📦 Tencent Cloud COS
• 📦 AWS S3
• 📦 Google Drive
• 📦 Dropbox
• 📦 More...

If you'd like to prioritize support for a specific cloud service, welcome to create a feature request in Issues!

🛠️ Development Guide

Tech Stack

• Flutter 3.27+: Cross-platform UI framework
• Riverpod: State management solution
• Drift (SQLite): Local database ORM
• Supabase: Cloud backup and sync service

Project Structure

lib/
├── data/           # Data models and database operations
├── pages/          # Application pages
├── widgets/        # Reusable components
├── cloud/          # Cloud service integration
├── l10n/           # Internationalization resources
├── providers/      # Riverpod state providers
└── utils/          # Utility functions

Development Commands

# Install dependencies
flutter pub get

# Code generation
dart run build_runner build --delete-conflicting-outputs

# Run tests
flutter test

# Build release version
flutter build apk --flavor prod --release

Contribution Guidelines

We welcome all forms of contributions! Please see our detailed Contributing Guide to learn how to participate:

• 🐛 Report Bugs
• 💡 Suggest Features
• 💻 Contribute Code
• 🌍 Contribute Translations
• 📝 Improve Documentation

Quick Start:

1. Fork this project
2. Create feature branch (git checkout -b feature/AmazingFeature)
3. Commit changes (git commit -m 'feat: add some feature')
4. Push to branch (git push origin feature/AmazingFeature)
5. Create Pull Request

For detailed standards, please refer to the Complete Contributing Guide.

📄 Open Source License

This project uses a Business Source License. Free for personal use, commercial use requires paid authorization. See LICENSE for details.

⚠️ Disclaimer

• This software is provided "as is" without any express or implied warranties
• Users are responsible for any data loss or financial loss caused by using this software
• Please ensure legal and compliant use of this software

💬 FAQ

Q: Can I use it normally without configuring cloud services? A: Absolutely! The app uses local storage by default, and all features work normally. You can still export CSV backups at any time.

Q: Should I choose Supabase or WebDAV? A:

• If you have a NAS device or private cloud, we recommend WebDAV (fully localized data)
• If you don't have a NAS, we recommend Supabase (free, stable, easy to configure)
• Both support complete sync functionality, choose based on your needs

Q: Why can't I upload after configuring WebDAV? A:

• Check if WebDAV service is enabled and port is correct
• Verify username and password are correct
• Some NAS WebDAV requires specific paths for write access (e.g., UGREEN Cloud requires /home/ path)
• Click "Test Connection" button to view detailed error messages

Q: Can I switch back to default mode after configuring custom cloud service? A: Yes, you can switch anytime. The saved custom configuration won't be lost and can be re-enabled.

Q: How to ensure data security? A:

• Use your own Supabase project or WebDAV server
• Regularly export CSV backups to local storage
• Use strong passwords and enable two-factor authentication (if supported)
• For WebDAV, recommend using HTTPS for encrypted transmission

Q: What data formats are supported? A: Currently supports CSV format for import/export, compatible with data formats from most mainstream accounting apps.

Q: How to sync data across multiple devices? A:

• Supabase: Configure same URL and anon key on all devices, log in with same account
• WebDAV: Configure same WebDAV server address and credentials on all devices

---

💝 Donate

Why We Need Your Support?

BeeCount is a completely free and open-source project with no ads or paid features. However, to make it available for iOS users, we need an Apple Developer Account ($99/year) to sign the app.

Your donation will be used for:

• 📱 Renew Apple Developer Account - Keep iOS TestFlight beta accessible ($99/year)
• 🔧 Support continuous development and maintenance - Keep the project actively developed

Donation Methods

🌍 International

• PayPal: https://paypal.me/sunxiaoyes

🇨🇳 China

Click to view QR codes

Alipay	WeChat Pay

🪙 Cryptocurrency

• USDT (TRC20): TKBV69B2AoU67p3vDhnJUbMJtZ1DxuUF5C
• Binance:

Click to view QR code

📊 Funding Progress

• 🎯 Goal: $99 (Apple Developer Account annual fee)
• 💰 Raised: ¥732 (≈ $101)
• 📈 Progress: 101.67% ✅

Progress: [██████████] 101.67% - 🎉 Goal Achieved!

Completed:

• ✅ Apple Developer Account registration (¥688/year, ≈$95/year)
• ✅ iOS TestFlight public beta launched
• ✅ Lightweight cloud server (¥79/year, ≈$11/year) - For ICP filing

Ongoing Costs:

• 📱 Apple Developer Account renewal: ¥688/year (≈$95/year)
• ☁️ Lightweight cloud server: ¥79/year (≈$11/year)

Total Annual Cost: ¥767/year (≈$106/year)

All donation fund usage will be transparently disclosed here.

🌟 Special Thanks to Our Supporters

Thank you to the following generous supporters (in chronological order):

• *Qiao - ¥12 - 2025-10-27 (WeChat)
• *Rui - ¥720 - 2025-10-27 (WeChat)
• *Hong - ¥50 - 2025-11-07 (Alipay)
• *Shao - ¥15 - 2025-11-09 (Alipay)
• *Ge - ¥6 - 2025-11-17 (WeChat)
• *Te - ¥15 - 2025-11-17 (WeChat)

---

📜 License

This project is licensed under the Business Source License:

• ✅ Personal Use - Completely Free
• ✅ Learning & Research - Completely Free
• ✅ Open Source Contribution - Welcome
• ❌ Commercial Use - Paid License Required

What is Commercial Use?

Commercial license is required for:

• Providing this software as part of commercial products or services
• Using this software in for-profit organizations
• Developing commercial products based on this software
• Providing paid cloud services based on this software

How to Obtain a Commercial License?

For commercial use, please contact us via:

• 📧 GitHub Issues
• 💬 Telegram Group

For detailed license terms, please see the LICENSE file.

---

🙏 Acknowledgments

Thanks to all friends who have contributed code, suggestions, and feedback to the BeeCount project!

If you have questions or suggestions, feel free to raise them in Issues or participate in discussions at Discussions.

BeeCount 🐝 - Making Accounting Simple and Secure