💰 Personal Expenses

A beautiful and efficient personal expense tracking mobile application built with Flutter 3.24+, featuring local database storage, interactive charts, and responsive design for Android and iOS devices.

🚀 Try it Live

⭐ Support this project

---

📋 Table of Contents

• Screenshots
• Features
• Getting Started
• CI/CD & Deployment
• Project Structure
• Technologies Used
• Contributing
• License

---

📱 Screenshots

---

✨ Features

📊 Core Functionality

• ✅ Save Daily Expenses - Track your spending with title, amount, and date
• ✅ Interactive Charts - Visual spending chart for recent 7 days
• ✅ Delete with Confirmation - Alert dialogue before deleting expenses
• ✅ Local Database - SQLite integration for persistent data storage
• ✅ Transaction History - View all your expenses in a scrollable list

🎨 User Experience

• ✅ Beautiful UI - Modern Material Design with custom theming
• ✅ Responsive Design - Optimized for both portrait and landscape modes
• ✅ Adaptive Layouts - Different UI arrangements based on orientation
• ✅ Custom Fonts - Google Fonts (Open Sans & Quicksand)
• ✅ Smooth Performance - Optimized rendering and database queries
• ✅ Empty State - Friendly illustration when no transactions exist

🚀 Technical Features

• ✅ Cross-platform - Works seamlessly on Android and iOS
• ✅ Offline-first - All data stored locally
• ✅ High Performance - Smooth scrolling and fast operations
• ✅ Type Safety - Full Dart type safety
• ✅ Modular Code - Reusable widgets and components

---

🚀 Getting Started

Prerequisites

Before you begin, ensure you have the following installed:

• Flutter SDK (3.35.6 or higher)

  flutter --version

• Dart SDK (3.5.0 or higher)
• Android Studio or VS Code with Flutter extensions
• Git

Installation

1. Clone the repository

   git clone https://github.com/Rezuanul-Islam-Fahim/personal_expenses.git
   cd personal_expenses

2. Install dependencies

   flutter pub get

3. Verify Flutter setup

   flutter doctor

Running the App

For Android

flutter run

Build APK (Android)

flutter build apk --release

---

🔄 CI/CD & Deployment

This project includes an automated CI/CD pipeline that builds and deploys the app to Appetize.io for instant browser-based testing.

🚀 Automated Deployment Features

• ✅ Automatic APK Building - Builds universal release APK on pull requests to master
• ✅ Appetize Integration - Deploys to Appetize.io for instant browser testing
• ✅ Smart App Management - Creates new apps or updates existing ones based on APPETIZE_PUBLIC_KEY
• ✅ Smart Caching - 3-layer caching (Java, Flutter SDK, Pub dependencies) for 3-5x faster builds
• ✅ Version Management - Automatic versioning with build numbers from pubspec.yaml
• ✅ Artifact Storage - 30-day APK artifact retention with direct download links via artifact ID
• ✅ PR Integration - Automatic deployment info with direct APK download links in pull request comments
• ✅ First-Time Setup Helper - Automatic instructions for saving public key on first deployment

⚡ Build Performance

Build Type	Duration	Caching
First Build	~10-15 min	Full build with all dependencies
Cached Build	~2-3 min	3-5x faster with 3-layer smart caching (Java, Flutter, Pub)

📚 Documentation

• Architecture Diagram - Visual workflow overview and pipeline stages

🎯 Quick Start CI/CD

1. Set up Appetize.io account and get your API token
2. Add GitHub Secret: APPETIZE_API_TOKEN (Settings → Secrets → Actions)
3. Create pull request to master branch - Workflow runs automatically
4. Check workflow output - View build results in GitHub Actions tab
5. Save public key (first deployment only):
   • Check workflow summary for the public key
   • Add APPETIZE_PUBLIC_KEY to GitHub Secrets
   • Future deployments will update the same app
6. Review deployment - Check PR comments for live preview URL and direct APK download link

That's it! The workflow automatically builds and deploys your app to Appetize.io on every PR to master, with direct download links using artifact IDs.

🔑 Required Secrets

Secret Name	Required	Purpose
APPETIZE_API_TOKEN	✅ Yes	Authenticates with Appetize.io API
APPETIZE_PUBLIC_KEY	⚠️ Recommended	Updates existing app (prevents creating new instances)

Note: Without APPETIZE_PUBLIC_KEY, each deployment creates a new app. Add it after first deployment to enable app updates.

---

📂 Project Structure

personal_expenses/
├── lib/
│   ├── main.dart                 # App entry point
│   ├── theme.dart                # App theme configuration
│   ├── global.dart               # Global constants
│   ├── models/                   # Data models
│   │   └── expense.dart          # Expense model
│   └── widgets/                  # Reusable UI components
│       ├── add_transaction.dart  # Add expense form
│       ├── chart.dart            # Weekly chart widget
│       ├── chartbar.dart         # Individual chart bar
│       ├── delete_tx_dialogue.dart
│       ├── no_transaction_image.dart
│       ├── transaction_list.dart # Transaction list view
│       └── tx_list_item.dart     # Single transaction item
├── assets/                       # Static assets
│   ├── fonts/                    # Custom fonts
│   └── images/                   # Images and illustrations
├── .github/                      # GitHub workflows and CI/CD
│   ├── workflows/
│   │   └── build-and-deploy-appetize.yml
│   ├── ARCHITECTURE.md           # CI/CD documentation
│   └── CONTRIBUTING.md           # Contributing guidelines
├── android/                      # Android-specific files
├── ios/                          # iOS-specific files
├── pubspec.yaml                  # Project dependencies
└── README.md                     # This file

---

🛠️ Technologies Used

Technology	Description
	UI framework
	Programming language
	Local database
	Design system
	CI/CD automation

Key Dependencies

• intl (^0.19.0): Internationalization and date formatting
• sqflite (^2.3.3): SQLite database plugin
• path (^1.9.0): Cross-platform path manipulation
• cupertino_icons (^1.0.8): iOS-style icons

---

🤝 Contributing

Contributions are what make the open-source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated.

How to Contribute

1. Fork the Project
2. Create your Feature Branch

   git checkout -b feature/AmazingFeature

3. Commit your Changes (following Conventional Commits)

   git commit -m 'feat: add some AmazingFeature'

4. Push to the Branch

   git push origin feature/AmazingFeature

5. Open a Pull Request

Coding Standards

• Follow Effective Dart guidelines
• Write meaningful commit messages (Conventional Commits)
• Add comments for complex logic
• Update documentation as needed

---

License

MIT License

Copyright (c) 2020 Rezuanul Islam Fahim

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.