quewen08/money-mint

MoneyMint Accounting System

A modern personal accounting system built on Beancount and Fava, featuring powerful backend services and a mobile-friendly frontend interface to help users easily manage their personal finances.

🚀 Project Overview

MoneyMint is an open-source personal financial management system designed to provide an intuitive interface and robust accounting features. The system adopts a decoupled architecture with a Python/Flask backend using Beancount as the core accounting engine, and a modern frontend built with Nuxt.js and Vue 3.

Core Advantages

• Beancount-based: Leverages professional double-entry accounting system to ensure financial data accuracy
• Modern Interface: Responsive design supporting both desktop and mobile devices
• Real-time Synchronization: SSE technology enables real-time data updates
• Flexible Deployment: Supports local deployment and Docker containerization
• Data Security: JWT authentication mechanism with data stored in local plain text files

📋 Features

Core Functionality

• Ledger Management: Support for multiple ledgers with data stored in secure plain text format
• Income & Expense Tracking: Complete double-entry accounting system supporting various transaction types
• Category Statistics: Financial data statistics by category, time, account, and other dimensions
• Chart Analysis: Visual charts displaying financial status and trends
• Account Management: Multi-account management including assets, liabilities, income, and expense accounts

Enhanced Features

• Transaction Copy: Quickly create similar transactions to improve accounting efficiency
• Smart Account Filtering: Account search and filtering functionality when adding transactions for easy multi-account selection
• Account Transaction Details: View all transaction records for a specific account in the account details page, supporting date filtering and pagination
• Real-time Data Updates: SSE technology enables real-time ledger data push updates
• User Authentication: Complete user login, registration, and permission management system

🛠️ Technology Stack

Backend

• Python 3.11: Main development language
• Flask: Web application framework
• Beancount: Core accounting engine
• Fava: Beancount's web interface (optional integration)
• Flask-JWT-Extended: JWT authentication
• Flask-CORS: Cross-origin resource sharing
• Flask-Bcrypt: Password encryption

Frontend

• Nuxt.js 3: Full-stack Vue.js framework solution
• Vue 3: Progressive JavaScript framework
• Tailwind CSS: Utility-first CSS framework
• TypeScript: Type-safe JavaScript superset
• Pinia: Vue 3 state management library

Data Storage

• Beancount Plain Text Ledger: Human-readable financial data format
• Local File System: Data stored locally ensuring privacy and security

📁 Project Structure

MoneyMint/
├── backend/                    # Python backend services
│   ├── app/                   # Application code
│   │   ├── main.py            # Main application entry
│   │   └── __init__.py        # Package initialization file
│   ├── data/                  # Ledger data directory
│   │   └── main.bean          # Default ledger file
│   ├── config/                # Configuration files directory
│   └── requirements.txt       # Python dependencies
├── frontend/                  # Nuxt frontend project
│   ├── assets/                # Static assets
│   ├── components/            # Vue components
│   ├── composables/           # Composable functions
│   │   └── useApi.ts          # API call encapsulation
│   ├── pages/                 # Page components
│   │   ├── index.vue          # Homepage/Dashboard
│   │   ├── accounts.vue       # Account management
│   │   ├── entries.vue        # Transaction records
│   │   └── login.vue          # Login page
│   ├── plugins/               # Nuxt plugins
│   ├── public/                # Public resources
│   ├── nuxt.config.ts         # Nuxt configuration
│   ├── package.json           # Node.js dependencies
│   └── tailwind.config.js     # Tailwind CSS configuration
├── Dockerfile                 # Docker build file
├── docker-compose.yml         # Docker Compose configuration
├── README.md                  # English documentation
└── README-zh.md               # Chinese documentation

🚀 Quick Start

Local Deployment

1. Backend Setup

bash
# Enter backend directory
cd backend

# Create virtual environment
python -m venv venv

# Activate virtual environment
# Windows
env\Scripts\activate
# Linux/macOS
source venv/bin/activate

# Install dependencies
pip install -r requirements.txt

# Run backend service
python app/main.py

The backend service will start at http://localhost:5000.

2. Frontend Setup

bash
# Enter frontend directory
cd frontend

# Install dependencies
npm install

# Start development server
npm run dev

The frontend development server will start at http://localhost:3000.

Docker Deployment

Quickly deploy the entire application using Docker Compose:

bash
# Build and start containers
docker-compose up -d

# Check container status
docker-compose ps

The application will be available at http://localhost:3000.

🔧 Configuration Options

Backend Configuration

Backend can be configured via environment variables or .env file:

Frontend Configuration

Frontend configuration file is located at frontend/nuxt.config.ts, main configuration items:

📖 User Guide

1. User Authentication

• When accessing the system for the first time, use the default admin account to log in:
  • Username: admin
  • Password: admin123
• You can change the password or create new users after logging in

2. Ledger Management

• The system automatically creates a default ledger file
• Ledgers can be managed through backend API or by directly editing ledger files
• Multi-ledger switching is supported (requires manual configuration)

3. Account Management

• View all accounts and their balances
• Click on an account name to view its transaction records
• Support date range filtering and pagination when viewing transaction records

4. Adding Transactions

• Select transaction type (income, expense, transfer, etc.)
• Fill in transaction date, amount, description, etc.
• Select relevant accounts and categories
• Use the copy function to quickly create similar transactions

5. Data Statistics

• Dashboard displays total income, total expenses, and net income
• Category statistics show the proportion of various expenses
• Chart analysis intuitively displays financial trends

🤝 Contribution Guidelines

Contributions of all kinds are welcome! Whether you're reporting bugs, suggesting new features, or submitting code directly, your support is greatly appreciated.

Contribution Process

1. Fork this repository
2. Create a feature branch (git checkout -b feature/AmazingFeature)
3. Commit your changes (git commit -m 'Add some AmazingFeature')
4. Push to the branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

Development Standards

• Follow existing code style
• Ensure code passes all tests before submission
• Add documentation for new features
• Provide clear commit messages

📄 License

This project is licensed under the MIT License - see the https://github.com/quewen08/MoneyMint/blob/master/LICENSE file for details.

📞 Contact

• Project address: https://github.com/quewen08/MoneyMint
• Issue feedback: https://github.com/quewen08/MoneyMint/issues

📦 Technical Documentation

• https://beancount.github.io/docs/
• https://flask.palletsprojects.com/
• Nuxt.js Official Documentation

🙏 Acknowledgments

Thanks to all the developers and users who have contributed to the MoneyMint project!

If you find MoneyMint helpful, please give us a ⭐ Star to support our work!