PocketWise

KO | EN

gitlite — search

#python #android #react #machine-learning #javascript #nodejs #java #php #kotlin #covid-19 #awesome #python3

★ 18 Open GitHub ↗

A modern personal finance management system based on FastAPI and Vue.js, providing comprehensive income and expenditure tracking, data analysis, and visualization capabilities.

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

<div align="right"> <a href="./README.md"><strong>English</strong></a> | <a href="./README_zh.md">简体中文</a> </div>

# 🏦 PocketWise

[![FastAPI](https://img.shields.io/badge/FastAPI-2.0+-green.svg)](https://fastapi.tiangolo.com/)
[![Vue.js](https://img.shields.io/badge/Vue.js-3.x-blue.svg)](https://vuejs.org/)
[![PrimeVue](https://img.shields.io/badge/PrimeVue-4.3+-orange.svg)](https://primevue.org/)
[![MySQL](https://img.shields.io/badge/MySQL-8.0+-orange.svg)](https://www.mysql.com/)
[![License](https://img.shields.io/badge/License-MIT-yellow.svg)](https://raw.githubusercontent.com/JuyaoHuang/PocketWise/master/)

## 📋 Project Overview

A modern personal finance management system based on **FastAPI and Vue.js**, providing comprehensive income and expenditure tracking, data analysis, and visualization capabilities. The system utilizes a front-end and back-end separation architecture, supporting multi-wallet management, intelligent classification, budget control, and real-time statistical analysis.

**🎯 Core Features**

- 💰 Multi-wallet account management
- 📊 Intelligent data visualization
- 🎯 Flexible budget control
- 🔄 Real-time data synchronization
- 📱 Responsive design

## ✨ Core Features

### 💰 Wallet Management

- **Multi-Wallet Support**: Create and manage multiple wallet accounts
- **Balance Tracking**: View your wallet balance and total assets in real time
- **Wallet Statistics**: View wallet summary information and usage analysis

### 📊 Transaction History

- **Income and Expenditure Record**: Supports both income and expense transaction types
- **Smart Classification**: Customize income and expense categories for easy statistical analysis
- **Flexible Search**:
  - Filter transaction records by wallet
  - Search by date range (supports multiple date formats)
  - Quick time range (this week/this month/this year/last week, etc.)
- **Transaction Details**: Record detailed information such as transaction object, description, and amount

### 📈 Data Analysis and Visualization

- **Dashboard**:
  - Total assets overview
  - Income and expenditure trend chart
  - Recent transaction history
- **Statistics**:
  - Income and expenditure distribution pie chart
  - Monthly/yearly trend analysis
  - Expenditures by category ranking
  - Customized time range analysis
- **Real-time Chart**: Dynamic data visualization based on Chart.js

### 🎯 Budget Management

- **Monthly Budget**: Set your monthly spending budget
- **Budget Tracking**: Monitor budget execution
- **Overspending Alert**: Get smart alerts when you're overspending

### ⚙️ System Settings

- **Category Management**: Customize income and expenditure categories
- **Wallet Configuration**: Create, edit, and delete wallets
- **Data Management**: Supports data cleanup and maintenance

## 🛠️ Technology Stack

### 🔧 Backend Technology Stack

- **🚀 Web Framework**: FastAPI 2.0+
- **📊 Database**: MySQL 8.0+ with SQLAlchemy ORM
- **✅ Data Validation**: Pydantic v2
- **🌐 Cross-origin Support**: CORSMiddleware
- **📋 Database Migration**: Alembic
- **📖 API Documentation**: Automatically Generate OpenAPI/Swagger
- **🔗 Database Connection**: PyMySQL
- **📅 Date Handling**: python-dateutil

### 🎨 Front-end Technology Stack

- **⚡ Front-end Framework**: Vue.js 3.4+ (Composition API)
- **🎨 UI Component Library**: PrimeVue 4.3+ + PrimeIcons
- **📊 Chart Visualization**: Chart.js 3.x
- **🌐 HTTP Client**: Axios 1.x
- **⚡ Build Tool**: Vite 5.x
- **🎯 Routing**: Vue Router 4.x
- **🎨 CSS Framework**: TailwindCSS + Sakai Template

### 🔨 Development Toolchain

- **📦 Package Management**: npm (frontend) + pip (backend)
- **🔍 Coding Standards**: ESLint + Prettier + Ruff
- **🔄 Version Control**: Git
- **📝 Development Environment**: VS Code + Extensions
- **🧪 API Testing**: Built-in FastAPI testing interface

## 🚀 Quick Start

It is recommended to first review the [Complete Startup Configuration](./项目运行指南.md)

### 📋 Prerequisites

**System Requirements**

- 🐍 **Python**: 3.8+ (3.11+ recommended)
- 📦 **Node.js**: 16+ (18+ LTS recommended)
- 🗄️ **MySQL**: 8.0+
- 💾 **Memory**: Minimum 2GB RAM
- 💿 **Storage**: 500MB+ available space

**Development Tools (Recommended)**

- 📝 **Editor**: VS Code with Python/Vue.js extensions
- 🔧 **API Testing**: Postman or built-in FastAPI documentation
- 📊 **Database Management**: MySQL Workbench or DBeaver

### 🔧 Backend startup

1. **📦 Dependency Installation**

```py
   cd bankend
   # Using a virtual environment is recommended
   python -m venv venv
   # Activate on Windows
   venv\Scripts\activate
   # Activate on Linux/Mac
   source venv/bin/activate
   # use conda
   conda activate your_conda_environment
   
   
   # Install dependencies (all required dependencies are included in this project)
   pip install -r requirements.txt
   # or 
   conda env update --name your_conda_environment --file environment.yml --prune
   ```

2. **🗄️ Database Configuration**

```py
   # Create a MySQL database
   mysql -u root -p
   CREATE DATABASE transcaler CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
   
   # Modify the database connection information in config/config.py
   DB_HOST = "localhost"
   DB_PORT = "3306"
   DB_USER = "root"
   DB_PASSWORD = "your_password" # Change to your password
   DB_NAME = "transcaler"
   ```

3. **📊 Database Initialization**

```py
   # Run the database initialization script
   python utils/init_database.py
   
   # Or use Alembic for migration
   alembic upgrade head
   ```

4. **🚀 Start the service**

```
   python start_server.py
   # or
   uvicorn api.server:app --reload --host 0.0.0.0 --port 8026
   ```

**✅ Startup success**

- 🌐 Service address: http://localhost:8026
- 📖 API documentation: http://localhost:8026/docs
- 🔍 ReDoc documentation: http://localhost:8026/redoc
- 💚 Health check: http://localhost:8026/health

### 🎨 前端启动

1. **📦 Dependency Installation**

```bash
   cd fronted/sakai-vue
   # Clear possible cache issues
   npm cache clean --force
   
   # Install dependencies
   npm install
   # Or use yarn
   yarn install
   ```

2. **⚡ Start the development server**

```bash
   # Start with a specified port (recommended)
   npm run dev -- --port 8040
   
   # Or use the default port
   npm run dev
   ```

3. **🏗️ Production Build**

```bash
   # Build for production
   npm run build
   
   # Preview the build results
   npm run preview
   ```

**✅ Startup success sign**

- 🌐 Development address: http://localhost:8040
- 🔥 Hot reload: Automatically refresh the page after code modification
- 📱 Responsive: Supports desktop and mobile access

## 📁 Project Structure

```bash
PocketWise/
├── 📁 bankend/ # 🔧 Backend service catalog
│ ├── 📁 api/ # 🌐 API interface layer
│ │ ├── server.py # 🚀 FastAPI main application service
│ │ ├── schema.py # 📋 Pydantic data model definition
│ │ └── old_server.py # 📜 Historical version backup
│ ├── 📁 data/ # 💾 Data access layer
│ │ ├── crud.py # 🔄 CRUD database operations
│ │ ├── models.py # 🏗️ SQLAlchemy ORM models
│ │ └── database.py # 🔗 Database connection configuration
│ ├── 📁 config/ # ⚙️ Application Configuration
│ │ └── config.py # 🔧 Database and Server Configuration
│ ├── 📁 alembic/ # 📈 Database Migrations
│ │ ├── versions/ # 📝 Migration Version Files
│ │ └── env.py # 🌐 Alembic Configuration
│ ├── 📁 utils/ # 🛠️ Utility Functions
│ │ ├── init_database.py # 🏗️ Database Initialization
│ │ └── clear_logs.py # 🧹 Log Cleanup Tool
│ ├── 📁 logs/ # 📊 System Logs
│ ├── start_server.py # 🚀 Service Startup Script
│ └── main.py # 🎯 Application Entry Point
├── 📁 fronted/ # 🎨 Front-end Application Directory
│ ├── 📁 src/ # 📂 Source Code Directory
│ │ ├── 📁 views/ # 📄 Page Components
│ │ │ ├── Dashboard.vue # 📊 Dashboard Homepage
│ │ │ ├── Details.vue # 💰 Transaction Details Management
│ │ │ ├── Statistics.vue # 📈 Statistics Analysis Page
│ │ │ ├── Budget.vue # 🎯 Budget Management Page
│ │ │ └── Settings.vue # ⚙️ System Settings Page
│ │ ├── 📁 services/ # 🔗 API Service Layer
│ │ │ ├── apiService.js # 🌐 HTTP client wrapper
│ │ │ ├── dataService.js # 📊 Data processing service
│ │ │ └── index.js # 📦 Service entry file
│ │ ├── 📁 config/ # 📋 Front-end configuration
│ │ │ └── api.js # 🔗 API endpoint configuration
│ │ ├── 📁 layout/ # 🏗️ Layout components
│ │ ├── 📁 components/ # 🧩 Common components
│ │ ├── 📁 router/ # 🗺️ Routing configuration
│ │ └── 📁 assets/ # 🎨 Static assets
│ ├── package.json # 📦 Front-end dependency configuration
│ ├── vite.config.js # ⚡ Vite build configuration
│ └── index.html # 🌐 Application entry HTML
├── 📁 Document Directory/ # 📚 Project Documentation
├── README.md # 📖 Project Description
├── Project Development Documentation.md # 📝 Detailed Development Documentation
├── budgets Development Documentation.md # 💰 Budgeting Functionality Documentation
├── Front-End and Back-End Integration Guide.md # 🔗 Integration Development Guide
└── Development Bug Log.md # 🐛 Problem Solving Record
```

**📂 Key Directory Description**

- `bankend/`: Complete FastAPI backend service, including API, data model, and CRUD operations
- `fronted/`: Vue.js 3 + PrimeVue frontend application, using the Composition API
- `alembic/`: Database version management and migration tool
- `services/`: Frontend data service layer, centralized management of API calls and data caching
- `Documents/`: Complete development documentation, including feature planning, API documentation, troubleshooting, etc.

## 🔧 API documentation

### 💰 Wallet Management API

- `GET /wallets/` - 📋 Get a list of all wallets
- `POST /wallets/` - ➕ Create a new wallet
- `GET /wallets/summary` - 📊 Wallet summary statistics
- `PUT /wallets/{name}/balance` - 💸 Update a wallet's balance
- `DELETE /wallets/{name}` - 🗑️ Delete a wallet (supports force deletion)

### 💸 Transaction Management API

- `GET /transactions/` - 📋 Get transaction records (supports paging and filtering)
- `POST /transactions/` - ➕ Create a new transaction record
- `PUT /transactions/{id}` - ✏️ Update a transaction record
- `DELETE /transactions/{id}` - 🗑️ Delete a transaction record (supports balance rollback)
- `GET /transactions/wallet/{name}` - 🏦 Filter by wallet
- `GET /transactions/date-range` - 📅 Query by date range
- `GET /transactions/quick-range` - ⚡ Quick time range query
- `GET /transactions/summary` - 📊 Transaction summary statistics
- `GET /transactions/summary_latest_months` - 📈 Revenue and expenditure statistics for the last N months

### 🏷️ Category Management API

- `GET /categories/` - 📋 Get all categories (including usage statistics)
- `POST /categories/` - ➕ Create a new category
- `PUT /categories/{id}/update` - ✏️ Update the category name and type
- `DELETE /categories/{id}` - 🗑️ Delete a category (supports force deletion)

### 🎯 Budget Management API

- `GET /budgets/` - 📋 Get a list of budgets (supports filtering)
- `POST /budgets/` - ➕ Create a budget plan
- `PUT /budgets/{id}` - ✏️ Update budget information
- `DELETE /budgets/{id}` - 🗑️ Delete a budget item
- `GET /budgets/summary/current` - 📊 Current budget usage statistics
- `GET /budgets/{id}` - 🔍 Get budget details

### 🔧 System Management API

- `GET /health` - ❤️ System Health Check
- `GET /` - 🏠 API Root Path Information

**📖 Full Documentation**: After starting the backend service, visit http://localhost:8026/docs to view the complete interactive API documentation.

## 🌐 Cross-origin Configuration

The system has pre-configured **CORS middleware**, supporting the following front-end access addresses:

**✅ Allowed Source Addresses**

- `http://localhost:8040` - 🎯 Primary development port
- `http://127.0.0.1:8040` - 📍 Local loopback address
- `http://localhost:3000` - 🔄 Alternate development port
- `http://localhost:4173` - 🔄 productionpreview port

**🔧 CORS Configuration Details**

- ✅ **Allow Credentials**: `allow_credentials=True`
- ✅ **Allow Methods**: `allow_methods=["*"]` (GET, POST, PUT, DELETE, etc.)
- ✅ **Allow Headers**: `allow_headers=["*"]` (Content-Type, Authorization, etc.)

> 💡 **Tip**: To add a new frontend address, please modify the CORS configuration in `bankend/api/server.py`

## 📊 Data schema design

The system uses a **normalized relational database design** to ensure data consistency and query performance:

### 🗄️ Core Data Table

| Table Name         | Description                                 | Core Fields                                                  | Relationship                |
| ------------------ | ------------------------------------------- | ------------------------------------------------------------ | --------------------------- |
| **wallets** 💰      | Wallet Account Table                        | `id`, `name`, `balance`, `created_time`                      | 1:N → transactions          |
| **categories** 🏷️   | Income and Expenditure Classification Table | `id`, `name`, `type`, `created_time`                         | 1:N → transactions, budgets |
| **transactions** 💸 | Transaction Record Table                    | `id`, `amount`, `type`, `description`, `wallet_id`, `category_id` | N:1 → wallets, categories   |
| **budgets** 🎯      | Budget Management Table                     | `id`, `name`, `amount`, `period`, `wallet_id`, `category_id` | N:1 → wallets, categories   |

### 🔗 Data relationship diagram

```
wallets (1) ──────── (N) transactions (N) ──────── (1) categories
   │                                                      │
   │                                                      │
   └────────────── (N) budgets (N) ──────────────────────┘
```

### 📋 Field detailed design

**💰 Wallets Table**

- `id`: Primary key, auto-increment ID
- `name`: Wallet name (unique, such as "Alipay", "WeChat", "Cash")
- `balance`: Current balance (DECIMAL precision)
- `created_time`: Creation time

**🏷️ Categories Table**

- `id`: Primary key, auto-increment ID
- `name`: Category name (e.g., "catering", "transportation", "salary")
- `type`: Category type (1 = expenses, 2 = income)
- `created_time`: Creation time

**💸Transactions Table**

- `id`: Primary key, auto-increment ID
- `amount`: Transaction amount (DECIMAL)
- `type`: Transaction type (1=expense, 2=income)
- `description`: Transaction description
- `wallet_id`: Associated wallet ID (foreign key)
- `category_id`: Associated category ID (foreign key)
- `expenditure_object`: Expenditure object
- `income_object`: Income object
- `transaction_date`: Transaction date
- `created_time`: Record creation time

**🎯 Budgets 预算表**

- `id`: 主键，自增ID
- `name`: 预算名称 (如"每日午餐预算")
- `amount`: 预算金额
- `period`: 预算周期 (daily/weekly/monthly)
- `wallet_id`: 关联钱包ID (可选)
- `category_id`: 关联分类ID (可选)
- `start_date`: 预算生效日期
- `created_time`: 创建时间

### 🔍 Database Optimization

- **Index Optimization**: Key query fields are indexed
- **Foreign Key Constraints**: Ensure data integrity
- **Character Set**: UTF8MB4 supports full Unicode
- **Transaction Support**: ACID features ensure data consistencys

## 🎨 Interface Features

### 📱 Responsive Design

- **🖥️ Desktop**: Fully functional experience, multi-column layout
- **📱 Mobile**: Adaptive responsive layout, touch-optimized
- **💻 Tablet**: Perfectly adapted for medium-sized screens

### 🎨 Modern UI Design

- **🎭 Theme System**: Modern component library based on PrimeVue 4.3+
- **🎨 Design Language**: Professional business style with Sakai Template
- **🌓 Theme Support**: Light theme (dark theme extension supported)
- **🎯 Interactive Experience**: Intuitive operation flow and user feedback

### 📊 Data Visualization

- **📈 Dynamic Charts**: Interactive charts powered by Chart.js 3.x
- **📊 Multiple Chart Types**: Pie, bar, line, and donut charts
- **🔄 Real-time Updates**: Data changes are instantly reflected in the chart.
- 📱**Touch-Friendly**: Supports gestures for zooming and interactivity.

### ⚡ Performance Optimization

- **🚀 Fast Loading**: Vite build tool, hot module replacement
- **💾 Smart Cache**: Data service layer caching mechanism
- **📦 On-Demand Loading**: Lazy loading of components and routes
- **🔄 No Refresh Experience**: SPA single-page application, smooth switching

### 🎯 User Experience

- **⌨️ Quick Actions**: Keyboard navigation support
- **🔍 Smart Search**: Live filtering and searching
- **📅 Date Selection**: Flexible date range selector
- **💾 Autosave**: Automatically save form data
- **🔔 Action Feedback**: Toast messages and confirmation dialogs

## 🔒 Security Features

### 🛡️ Data Security

- **✅ Input Validation**: Strict data validation for Pydantic v2 models
- **🚫 SQL Injection Protection**: Parameterized queries for SQLAlchemy ORM
- **🔒 Data Type Checking**: Strong type checking prevents type errors
- **📊 Data Integrity**: Foreign key constraints and transaction support

### 🌐 Network Security

- **🔒 CORS Protection**: Strictly restrict cross-origin access
- **🛡️ Request Restrictions**: FastAPI's built-in security middleware
- **🔐 HTTPS Support**: SSL/TLS encryption for production environments
- **📋 Request Logging**: Comprehensive API access logging

### 🧹 Error Handling

- **📋 Unified Response**: Standardized error response format
- **🔍 Detailed Log**: Complete error stacktrace and context
- **🚫 Information Leakage Prevention**: Protect sensitive information in production environments
- **⚡ Graceful Degradation**: Fallback handling for service exceptions

### 💾 Data Backup

- **🔄 Regular Backup**: Recommendations for regular MySQL data backups
- **📝 Migration History**: Alembic database version control
- **🔐 Sensitive Data**: Environment variable storage for sensitive information such as passwords

> ⚠️ **Note**: This project is a personal financial management system and is recommended for private use. For production deployment, please configure additional security measures such as authentication and API rate limiting.

## 📝 Development Notes

### 🔧 Development Configuration

1. **🌐 Port Configuration**: Defaults to `8026` for the backend and `8040` for the frontend
2. **🗄️ Database Connection**: Ensure MySQL 8.0+ is running properly
3. **🌍 Environment Variables**: Supports overriding the default configuration using `.env` files or system environment variables
4. **📖 API Documentation**: After starting the backend, visit `/docs` or `/redoc` to view the full documentation

### 🐛 Common Problem Solving

1. **❌ CORS Cross-Origin Error**: Check if the frontend port is 8040, or modify the backend CORS configuration.
2. **🔌 Database Connection Failure**: Verify that the MySQL service is started and check the username and password configuration.
3. **📦 Dependency Installation Failure**: Clear the npm/pip cache and use a domestic mirror.
4. **🚀 Port Usage**: Use `lsof -i :8026` (Mac/Linux) or `netstat -ano | findstr :8026` (Windows) to check.

### 🔄 Development Process Recommendations

1. **🏗️ Database First**: Ensure database connection and initialization are successful.
2. **🔧 Backend Testing**: Use `/docs` to test that the API interface is working properly.
3. **🎨 Frontend Development**: Confirm that the backend API is available before launching the frontend.
4. **📊 Data Synchronization**: Ensure consistency in frontend and backend data formats.

### 📈 Performance Optimization Suggestions

1. **💾 Database Indexing**: Consider adding indexes to optimize queries for large amounts of data.
2. **🔄 API Caching**: Consider adding Redis caching for high-frequency query interfaces.
3. **📦 Front-end Packaging**: Use `npm run build` to build optimized versions for production environments.
4. **🖼️ Static Resources**: Use CDN to accelerate static resources such as images.

## 🤝 Contribution Guidelines

### 📋 Contribution Process

1. **🍴 Fork the project**: Click the Fork button in the top-right corner to clone the project.
2. **🌿 Create a branch**: `git checkout -b feature/your-feature-name`
3. **💻 Develop the feature**: Follow the project's coding standards.
4. **✅ Test and verify**: Ensure the new feature works correctly and does not break existing features.
5. **📝 Commit code**: `git commit -m "feat: add new feature description"`
6. **📤 Push the branch**: `git push origin feature/your-feature-name`
7. **🔄 Create a pull request**: Create a pull request on GitHub

### 📏 Coding Standards

- **🐍 Python**: Follow PEP 8 and use Ruff for formatting
- **🎨 JavaScript**: Use ESLint + Prettier for formatting
- **💬 Commit Message**: Use Conventional Commits
- **📖 Documentation**: New features require documentation

### 🐛 Bug Report

Please provide the following information in your Issues:

- 🔍 **Issue Description**: A detailed description of the issue you encountered
- 🔄 **Reproduction Steps**: Provide reproducible steps
- 🌍 **Environment Information**: Operating system, browser, Python/Node.js version
- 📸 **Screenshots and Logs**: If possible, provide screenshots or logs of the error.

### 💡 Feature Suggestions

- 🎯 **Clear Requirements**: Clearly describe the proposed functionality and usage scenarios.
- 🎨 **Interface Design**: If UI is involved, provide a simple interface design idea.
- 🔧 **Technical Solution**: If you have any technical suggestions, please provide detailed explanations.

## 📄 License

This project is licensed under the MIT License. See the LICENSE file for details.

## 🆘 Support & Feedback

If you encounter issues or have suggestions for improvements, please submit feedback through Issues.

## 📈 Version History

### 🏷️ Current Version: v2.2.0 (September 24, 2025)

**🆕 Latest Update**

- ✅ Complete budget management system (supports daily/weekly/monthly budgeting)
- ✅ Improved category management functionality (covers addition, deletion, modification, and query)
- ✅ Transaction deletion functionality (supports rollback on errors)
- ✅ Performance optimization (reduces API calls from 6 to 1)
- ✅ Improved data synchronization mechanism

**📊 Feature Completeness**

- 💰 Wallet Management: **100%** ✅
- 💸 Transaction History: **100%** ✅
- 📊 Data Analysis: **100%** ✅
- 🎯 Budget Control: **100%** ✅
- ⚙️ System Settings: **100%** ✅

### 🎯 Development Roadmap

- 📱 Mobile App Development
- 🌙 Dark Theme Support
- 📊 More Chart Types
- 🔐 User Authentication System
- 📤 Data Import and Export
- 🌐 Multi-Language Support

**👨‍💻 Development Team**: PocketWise Development Team
**📅 Last Update**: September 24, 2025
**📄 License**: MIT License
**🌟 Project Status**: 🟢 Production Ready

### 🌟 If this project is helpful to you, please give it a ⭐ Star!

**💡 Report Issues** | **🔧 Feature Suggestions** | **🤝 Contribute**

[📖 View full document](./Docs/detailedDevelopmentDocumentation.md) | 🐛 Report an issue | [📖Full startup configuration](./PocketWiseGuide.md) | [📊 API Documentation](http://localhost:8026/docs)

PocketWise

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README