BillBucket

![Bill Bucket Banner](/BillBucket/images/github-banner.png) # 💰 Bill Bucket **A beautiful, intuitive Flutter app to manage your recurring bills and plan your finances with ease.** [![Flutter](https://img.shields.io/badge/Flutter-3.9.2+-02569B?logo=flutter&logoColor=white)](https://flutter.dev) [![Dart](https://img.shields.io/badge/Dart-3.9.2+-0175C2?logo=dart&logoColor=white)](https://dart.dev) [![License](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE) [![Version](https://img.shields.io/badge/Version-1.0.0-blue.svg)](pubspec.yaml) [![Platform](https://img.shields.io/badge/Platform-Android%20%7C%20iOS-lightgrey)](https://github.com/Parth-Patel01/BillBucket) [Features](#-features) • [Screenshots](#-screenshots) • [Installation](#-installation) • [Usage](#-usage) • [Tech Stack](#-tech-stack) • [Architecture](#-architecture) • [Contributing](#-contributing)

📖 About

Bill Bucket is a modern, offline-first mobile application designed to help you effortlessly manage your recurring bills. Whether you’re tracking weekly subscriptions, monthly utilities, or yearly insurance payments, Bill Bucket provides a clean, intuitive interface to keep your finances organized.

With smart calculations for monthly costs and recommended weekly transfers, you’ll always know how much to set aside for your bills account. The app features beautiful custom theming, smooth animations, and a robust data persistence layer that works completely offline.

✨ Features

🎯 Core Functionality

📝 Bill Management: Add, edit, and delete recurring bills with ease
📅 Smart Due Dates: Track next due dates with automatic calculations based on frequency
💰 Financial Insights:
- Calculate total monthly cost across all bills
- Get recommended weekly transfer amounts
- View upcoming bills in the next 14 days
✅ Payment Tracking: Mark bills as paid and automatically calculate next due date
🔄 Undo Support: Easily undo payments or restore deleted bills

🎨 User Experience

🌓 Theme Support: Beautiful light and dark themes with system preference detection
🎭 Custom Branding: Elegant typography using Baloo2 and Nunito fonts
📱 Responsive Design: Optimized for all screen sizes
⚡ Smooth Animations: Polished interactions with haptic feedback
🔍 Smart Filtering: Filter bills by frequency or view overdue items
📊 Visual Indicators: Color-coded overdue bills and intuitive icons

💾 Data Management

🔒 Offline-First: All data stored locally using Hive
💪 Persistent Storage: Your bills are saved securely on your device
🚀 Fast Performance: Instant load times with efficient data structures
🔄 State Management: Clean architecture with Provider pattern

📸 Screenshots

🚀 Installation

Prerequisites

Flutter SDK: 3.9.2 or higher
Dart SDK: 3.9.2 or higher
Android Studio / VS Code with Flutter extensions
Android SDK (for Android development)
Xcode (for iOS development, macOS only)

Setup Instructions

Clone the repository

git clone https://github.com/Parth-Patel01/BillBucket.git
cd BillBucket

Install dependencies
```
flutter pub get
```

Generate Hive adapters (if needed)

flutter pub run build_runner build --delete-conflicting-outputs

Run the app
```
flutter run
```

Building for Production

Android:

flutter build apk --release
# or for App Bundle
flutter build appbundle --release

iOS:

flutter build ios --release

💻 Usage

Adding a Bill

Tap the + floating action button on the dashboard
Enter the bill name (e.g., “Netflix Subscription”)
Enter the amount
Select the frequency (Weekly, Fortnightly, Monthly, or Yearly)
Choose the next due date
Tap Add bill

Managing Bills

View Details: Tap any bill to see full information
Mark as Paid: Open a bill and tap “Mark as paid today” to update the next due date
Edit: Tap the edit button to modify bill details
Delete: Swipe left on a bill or use the delete button in the detail screen
Filter: Use the filter chips to view bills by frequency or overdue items

Dashboard Features

Monthly Cost: See your total monthly bill expenses at a glance
Weekly Transfer: Get a recommended weekly transfer amount to cover all bills
Upcoming Bills: View bills due in the next 14 days
Filter & Sort: Easily find bills by frequency or sort by due date

🛠 Tech Stack

Core Technologies

Flutter - Cross-platform UI framework
Dart - Programming language

State Management

Provider - State management solution

Data Persistence

Hive - Fast, lightweight NoSQL database
Hive Flutter - Flutter integration for Hive

Utilities

UUID - Unique identifier generation
Intl - Internationalization and formatting
Package Info Plus - App metadata
URL Launcher - External link handling

Development Tools

Flutter Lints - Linting rules
Build Runner - Code generation
Hive Generator - Hive adapter generation

🏗 Architecture

Bill Bucket follows a clean, maintainable architecture pattern:

lib/
├── main.dart                 # App entry point
├── models/                   # Data models
│   ├── bill.dart            # Bill entity
│   └── app_settings.dart    # App settings
├── providers/                # State management
│   ├── bill_provider.dart   # Bill business logic
│   └── settings_provider.dart # Settings management
├── screens/                  # UI screens
│   ├── dashboard_screen.dart
│   ├── add_edit_bill_screen.dart
│   ├── bill_detail_screen.dart
│   └── settings_screen.dart
├── widgets/                  # Reusable widgets
│   └── animated_press.dart
├── utils/                    # Utilities
│   ├── bill_icons.dart      # Icon mapping
│   └── formatters.dart     # Formatting helpers
└── theme/                    # Theming
    └── app_theme.dart       # Theme configuration