Ultimate Finance App

A comprehensive Flutter application for managing personal finances locally. Take complete control of your money with an intuitive interface for tracking income, expenses, transactions, and financial goals.

📱 Features

• Authentication: Secure user authentication using Firebase Auth
• Dashboard: Overview of your financial status and key metrics
• Cash Flow Management: Track income and expenses with detailed transaction groups and categories
• Transaction Tracking: Record and manage all financial transactions
• Wallet Management: Monitor wallet balances and transactions
• Spending Analysis: Visualize spending patterns with charts and analytics
• Local Storage: Data stored locally using Hive for offline-first functionality
• Dark Mode Support: Beautiful dark and light themes
• Firebase Integration: Cloud Firestore for data synchronization and Firebase Remote Config

🛠️ Tech Stack

Core Technologies

• Flutter: 3.35.4 (via FVM)
• Dart: ^3.8.1
• Firebase: Authentication, Firestore, Remote Config
• State Management: BLoC (flutter_bloc ^9.1.1)
• Local Storage: Hive (^2.2.3)
• Dependency Injection: GetIt (^7.6.7) + Injectable (^2.4.1)
• Routing: GoRouter (^16.2.1)
• Charts: FL Chart (^1.1.0)

Development Tools

• Code Generation: Freezed (^3.2.3), Build Runner (^2.7.1)
• Testing: flutter_test, bloc_test (^10.0.0), mocktail (^1.0.1)
• Linting: flutter_lints (^5.0.0)

📋 Prerequisites

• Flutter SDK 3.35.4 (install via FVM)
• Dart SDK ^3.8.1
• Firebase project configured
• Android Studio / Xcode (for mobile development)
• Git

🚀 Getting Started

1. Clone the Repository

git clone <repository-url>
cd ultimate_finance_app

2. Install FVM (Flutter Version Management)

# macOS/Linux
brew tap leoafarias/fvm
brew install fvm

# Or using pub
dart pub global activate fvm

3. Install Flutter Version

fvm install 3.35.4
fvm use 3.35.4

4. Install Dependencies

fvm flutter pub get

5. Firebase Setup

1. Copy your Firebase configuration files:

   • Android: google-services.json → android/app/
   • iOS: GoogleService-Info.plist → ios/Runner/

2. Ensure Firebase is properly initialized in your Firebase console.

6. Generate Code

Run code generation for Freezed and Injectable:

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

7. Run the App

# Development
fvm flutter run

# Specific platform
fvm flutter run -d chrome  # Web
fvm flutter run -d ios     # iOS
fvm flutter run -d android # Android

📁 Project Structure

lib/
├── common/              # Shared utilities and components
│   ├── remoteconfig/   # Remote config implementations
│   ├── repositories/   # Shared repositories
│   ├── router/         # App routing configuration
│   ├── services/       # Shared services (Hive, Remote Config)
│   ├── theme/          # App themes and styling
│   ├── utils/          # Utility functions
│   └── widgets/        # Reusable widgets
├── di/                 # Dependency injection
│   ├── injection.dart            # Injectable configuration
│   ├── injection.config.dart     # Generated DI config
│   └── injection_manual.dart     # Manual DI setup
├── feature/            # Feature modules
│   ├── auth/          # Authentication
│   │   ├── data/      # Models, repositories, services
│   │   └── presentation/  # BLoC, views, widgets
│   ├── cash_flow/     # Cash flow management
│   ├── dashboard/     # Dashboard screen
│   ├── spending/      # Spending analysis
│   └── wallet/        # Wallet management
└── main.dart          # App entry point

test/                   # Test files
├── feature/           # Feature-specific tests
└── widget_test.dart   # Widget tests

🏗️ Architecture

The app follows Clean Architecture principles with BLoC pattern for state management:

• Presentation Layer: BLoC, Views, Widgets
• Data Layer: Models, Repositories, Services
• Domain Layer: Business logic and entities
• Dependency Injection: GetIt + Injectable for service location

State Management

• BLoC Pattern: Using flutter_bloc for predictable state management
• Events: User actions trigger events
• States: UI reacts to state changes
• Repository Pattern: Abstraction layer between data sources and business logic

🧪 Testing

Run Tests

# All tests
fvm flutter test --no-pub -r compact --coverage

# Specific test file
fvm flutter test test/feature/cash_flow/data/models/transaction_group_test.dart

# Integration tests
fvm flutter test integration_test/app_test.dart

Test Coverage

# Generate coverage report
fvm flutter test --coverage

# View coverage (requires lcov)
genhtml coverage/lcov.info -o coverage/html
open coverage/html/index.html

Testing Tools

• Unit Tests: flutter_test
• BLoC Tests: bloc_test for testing state transitions
• Mocking: mocktail for creating test doubles
• Widget Tests: Test individual widgets in isolation

🔧 Development Commands

Code Generation

# Watch mode (auto-generate on file changes)
fvm flutter pub run build_runner watch --delete-conflicting-outputs

# One-time generation
fvm flutter pub run build_runner build --delete-conflicting-outputs

Linting

# Analyze code
fvm flutter analyze

# Fix auto-fixable issues
fvm flutter fix

Build

# Android APK
fvm flutter build apk --release

# Android App Bundle
fvm flutter build appbundle --release

# iOS
fvm flutter build ios --release

# Web
fvm flutter build web --release

📦 Key Dependencies

State Management & Architecture

• bloc & flutter_bloc: State management
• get_it: Dependency injection
• injectable: Code generation for DI
• freezed: Immutable classes and unions

Data & Storage

• hive & hive_flutter: Local NoSQL database
• cloud_firestore: Cloud database
• firebase_auth: Authentication
• firebase_remote_config: Remote configuration

UI & Navigation

• go_router: Declarative routing
• fl_chart: Beautiful charts
• equatable: Value equality

Utilities

• gsheets: Google Sheets integration (optional)

🎨 Theming

The app includes a custom green finance theme with:

• Light theme: Green-based color scheme
• Dark theme: Dark variant with green accents
• Automatic theme switching based on system preferences

🔐 Authentication Flow

1. User logs in via Firebase Auth
2. Authentication state is managed by AuthBloc
3. Router redirects based on auth state
4. Protected routes require authentication

📊 Data Models

TransactionGroup

• Groups transactions by category (income, expense, income_debt, loan)
• Predefined groups for income and expenses

Transaction

• Represents individual financial transactions
• Includes amount, date, category, and metadata

TransactionCategory

• Subcategories within transaction groups
• Links to parent group via groupId

🌐 Firebase Configuration

The app uses Firebase for:

• Authentication: User login and registration
• Firestore: Optional cloud data synchronization
• Remote Config: Feature flags and remote configuration

🤝 Contributing

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

📝 License

This project is private and not published.

📞 Support

For issues and questions, please open an issue in the repository.

🔄 Version

Current version: 1.0.0+1

---

Built with ❤️ using Flutter