💰 PocketPal

A comprehensive cross-platform personal finance management application with gamified goals, real-time insights, and full-stack API integration.

---

📖 Project Overview

PocketPal is a modern financial tracking application that makes managing personal finances engaging and intuitive. Unlike traditional budget apps, PocketPal combines powerful financial analytics with gamification elements to motivate users to achieve their savings goals.

Problem Statement

Most people struggle to track their expenses consistently and find traditional finance apps boring or overwhelming. PocketPal solves this by:

• Making finance tracking visual and interactive with beautiful charts and animations
• Gamifying savings goals with quests, achievements, and progress tracking
• Providing real-time insights into spending patterns
• Offering a clean, modern interface that's actually enjoyable to use

Target Audience

• Young professionals starting their financial journey
• Budget-conscious individuals who want better spending visibility
• Anyone looking for a more engaging alternative to spreadsheets or complex finance software

What Makes It Unique

✨ Gamified Goals & Achievements - Turn saving money into a rewarding challenge
🎨 Beautiful UI/UX - Smooth animations and modern Material Design
📊 Real-Time Analytics - Interactive charts and spending breakdowns
🔌 Full-Stack Integration - RESTful API backend demonstrating production-ready architecture
⚙️ Highly Customizable - Multiple currencies, themes, and security options

---

✨ Features

🏠 Home Dashboard

• Real-time balance tracking with income vs expenses breakdown
• Savings progress cards showing goal completion percentage
• Weekly spending chart with interactive bar graph
• Top spending categories at a glance
• Pull-to-refresh for instant data updates
• Animated transitions and smooth Hero animations

💳 Wallet & Transactions

• Complete transaction management (view, add, search, filter)
• Smart filtering by type (All/Income/Expense)
• Real-time search across all transactions
• Quick-add form for instant transaction logging
• Category-based organization with visual icons
• Color-coded entries (green for income, red for expenses)

🎯 Goals & Quests

• Gamified financial challenges (e.g., "No Spend Weekend", "Save $500")
• Progress tracking with visual progress bars
• Achievement system with earned badges
• Custom goal creation with emoji selection
• Deadline tracking with day counters
• Scrollable quest list with overflow handling

📊 Insights & Analytics

• Interactive pie charts for spending breakdown
• Monthly trend analysis comparing income vs expenses
• Category-wise spending with percentages
• Financial health indicators
• Data visualization using FL Chart library

👤 Profile & Settings

• Multi-currency support (USD, EUR, GBP, INR, JPY, CNY, AUD, CAD)
• Notification management for expense reminders and budget alerts
• Security options (PIN, Biometric, None)
• Theme switching (Light, Dark, System)
• Data export functionality (CSV/PDF)
• User profile with avatar and stats
• Sign out capability

🔌 API Integration (Demo)

• RESTful API integration with Node.js backend
• 6 functional endpoints (health, summary, transactions, insights, goals)
• Real-time data synchronization
• POST request handling for adding transactions
• Comprehensive error handling with user-friendly messages
• Loading states and retry mechanisms
• Network error detection

🎨 UI/UX Features

• Animated splash screen with fade + scale transitions
• Hero transitions between screens
• Shimmer loading effects
• Smooth page transitions
• Responsive design adapting to all screen sizes
• Dark theme optimized for OLED displays
• Custom fonts using Google Fonts

---

🛠️ Tech Stack

Frontend (Mobile/Web/Desktop)

Technology	Version	Purpose
Flutter	3.8.1+	Cross-platform UI framework for building natively compiled applications
Dart	3.8.1+	Programming language optimized for UI development
Riverpod	3.3.1	State management solution with compile-time safety and provider pattern
GoRouter	17.0.0	Declarative routing with deep linking support
FL Chart	0.68.0	Beautiful, animated charts for data visualization
Google Fonts	6.3.2	Custom typography from Google Fonts library
Shimmer	3.0.0	Skeleton loading animation for better UX
Intl	0.20.2	Internationalization and date/number formatting
Percent Indicator	4.2.3	Progress indicators for goals and achievements
HTTP	1.2.0	HTTP client for API communication
UUID	4.5.3	Unique identifier generation
Cached Network Image	3.4.1	Image caching and lazy loading

Backend (API Server)

Technology	Version	Purpose
Node.js	14+	JavaScript runtime for server-side execution
Express.js	4.18.2	Web framework for building RESTful APIs
CORS	2.8.5	Cross-Origin Resource Sharing middleware
Body Parser	1.20.2	Request body parsing middleware

Database

Technology	Purpose
In-Memory Storage	Mock data storage for demo purposes (production would use PostgreSQL/MongoDB)

Development Tools

Tool	Purpose
Nodemon	3.0.1 - Auto-restart server on file changes during development
Flutter DevTools	Debugging and performance profiling
Dart Analyzer	Static code analysis and linting

---

📁 Project Structure

pocketpal/
├── android/                          # Android platform-specific code
├── ios/                              # iOS platform-specific code
├── web/                              # Web platform-specific code
├── windows/                          # Windows platform-specific code
├── linux/                            # Linux platform-specific code
├── macos/                            # macOS platform-specific code
├── assets/                           # Static assets (images, fonts)
│   └── images/
│       └── splash_logo.png          # Splash screen logo
├── BACKEND/                          # Node.js Express API server
│   ├── server.js                    # Main Express server with 6 API endpoints
│   ├── package.json                 # Backend dependencies
│   └── README.md                    # Backend documentation
├── lib/                              # Flutter application source code
│   ├── main.dart                    # Application entry point with GoRouter
│   ├── splash_screen.dart           # Animated splash screen
│   ├── api_service.dart             # Centralized API client with error handling
│   ├── api_models.dart              # Data models (Summary, Transaction, Insights, Goal)
│   ├── api_demo_screen.dart         # API integration demo UI
│   ├── core/                         # Core utilities and configurations
│   │   ├── theme/
│   │   │   ├── app_theme.dart       # Material theme configuration
│   │   │   └── app_colors.dart      # Color palette constants
│   │   └── utils/
│   │       └── formatters.dart      # Date and currency formatters
│   ├── features/                     # Feature-based modules
│   │   ├── home/                     # Home dashboard feature
│   │   │   ├── domain/
│   │   │   │   └── home_models.dart # Domain models for home
│   │   │   ├── presentation/
│   │   │   │   ├── screens/
│   │   │   │   │   ├── home_screen.dart    # Home dashboard UI
│   │   │   │   │   └── profile_screen.dart # Profile & settings UI
│   │   │   │   ├── widgets/
│   │   │   │   │   ├── balance_card.dart      # Balance display widget
│   │   │   │   │   ├── savings_goal_card.dart # Savings progress widget
│   │   │   │   │   ├── weekly_bar_chart.dart  # Weekly spending chart
│   │   │   │   │   └── top_categories_row.dart # Top categories widget
│   │   │   │   └── providers/
│   │   │   │       ├── home_providers.dart    # Riverpod providers for home
│   │   │   │       ├── profile_providers.dart # Profile state providers
│   │   │   │       ├── profile_models.dart    # Profile data models
│   │   │   │       └── settings_providers.dart # Settings state management
│   │   │   └── data/
│   │   │       └── home_repository.dart # Data layer for home
│   │   ├── wallet/                   # Wallet & transactions feature
│   │   │   ├── domain/
│   │   │   │   └── wallet_models.dart # Transaction models
│   │   │   └── presentation/
│   │   │       ├── screens/
│   │   │       │   └── wallet_screen.dart # Wallet UI
│   │   │       ├── widgets/
│   │   │       │   ├── filter_chip_bar.dart   # Transaction filters
│   │   │       │   ├── quick_add_form.dart    # Add transaction form
│   │   │       │   └── transaction_list.dart  # Transaction list view
│   │   │       └── providers/
│   │   │           └── wallet_providers.dart # Wallet state management
│   │   ├── goals/                    # Goals & quests feature
│   │   │   ├── domain/
│   │   │   │   └── goals_models.dart # Goal and quest models
│   │   │   ├── presentation/
│   │   │   │   ├── goals_screen.dart  # Goals UI
│   │   │   │   └── goals_widgets.dart # Quest cards, achievement badges
│   │   │   └── providers/
│   │   │       └── goals_providers.dart # Goals state management
│   │   └── insights/                 # Analytics & insights feature
│   │       ├── domain/
│   │       │   └── insights_models.dart # Analytics models
│   │       ├── presentation/
│   │       │   ├── insights_screen.dart # Insights UI
│   │       │   └── insights_widgets.dart # Chart components
│   │       └── providers/
│   │           └── insights_providers.dart # Insights state
│   └── shared/                        # Shared components
│       └── screens/
│           └── main_scaffold.dart    # Bottom navigation scaffold
├── test/                              # Unit and widget tests
│   └── widget_test.dart              # Sample widget tests
├── .gitignore                         # Git ignore rules
├── pubspec.yaml                       # Flutter dependencies
├── analysis_options.yaml              # Dart analyzer configuration
├── API_INTEGRATION_README.md          # API integration guide
├── verify_api_integration.sh          # Setup verification script
└── README.md                          # This file

---

⚙️ Prerequisites

Before running PocketPal, ensure you have the following installed:

Required Software

Software	Minimum Version	Download Link
Flutter SDK	3.8.1 or higher	flutter.dev
Dart SDK	3.8.1+ (bundled with Flutter)	Included with Flutter
Node.js	14.0.0 or higher	nodejs.org
npm	6.0.0 or higher	Included with Node.js
Git	Latest	git-scm.com

Platform-Specific Requirements

For Android Development:

• Android Studio (latest stable version)
• Android SDK 21 or higher
• Android Virtual Device (AVD) or physical device

For iOS Development (macOS only):

• Xcode 14.0 or higher
• CocoaPods 1.11.0 or higher
• iOS Simulator or physical device

For Web Development:

• Chrome browser (latest version)

For Desktop Development:

• Windows: Visual Studio 2022 with C++ tools
• macOS: Xcode command-line tools
• Linux: Clang, CMake, GTK development headers

---

🚀 Getting Started

Step 1: Clone the Repository

git clone https://github.com/gopal5587/POCKETPAL.git
cd POCKETPAL

Step 2: Install Flutter Dependencies

flutter pub get

Step 3: Install Backend Dependencies

cd BACKEND
npm install
cd ..

Step 4: Configure API Base URL (For Physical Devices)

If testing on a physical device, update the API base URL in lib/api_service.dart:

// Find your computer's IP address:
// Windows: Run 'ipconfig' in CMD
// Mac/Linux: Run 'ifconfig' in Terminal

// Update line 36 in api_service.dart:
const String computerIp = 'YOUR_IP_ADDRESS'; // e.g., '192.168.1.5'

// Then uncomment line 46 for physical Android device:
return 'http://$computerIp:3000';

Platform-specific URLs:

• Android Emulator: http://10.0.2.2:3000 (default)
• iOS Simulator: http://localhost:3000
• Physical Device: http://YOUR_IP:3000
• Desktop: http://localhost:3000

Step 5: Start the Backend Server

Open a new terminal and run:

cd BACKEND
npm start

You should see:

╔════════════════════════════════════════════════╗
║      PocketPal Mock API Server Running        ║
╚════════════════════════════════════════════════╝
🚀 Server: http://localhost:3000

Keep this terminal running!

Step 6: Run the Flutter App

In a separate terminal:

# For development
flutter run

# For specific platform
flutter run -d chrome        # Web
flutter run -d windows       # Windows
flutter run -d macos         # macOS
flutter run -d <device-id>   # Mobile device

Step 7: Build for Production

# Android APK
flutter build apk --release

# Android App Bundle (for Play Store)
flutter build appbundle --release

# iOS (macOS only)
flutter build ios --release

# Web
flutter build web --release

# Windows
flutter build windows --release

# macOS
flutter build macos --release

# Linux
flutter build linux --release

Step 8: Run Production Build

# Android: Install the APK from build/app/outputs/flutter-apk/app-release.apk

# Web: Serve the build/web directory
cd build/web
python -m http.server 8000

# Desktop: Run executable from build/<platform>/release/

---

🔑 Environment Variables

Backend Environment Variables

Currently, the backend uses in-memory storage and does not require environment variables. For production deployment, you would configure:

Variable	Description	Required	Default
PORT	Backend server port	No	3000
NODE_ENV	Environment mode	No	development
DATABASE_URL	Database connection string	No	N/A (in-memory)
JWT_SECRET	Secret key for authentication	No	N/A (not implemented)

Frontend Configuration

The frontend reads configuration from lib/api_service.dart:

Configuration	Description	Default
baseUrl	Backend API base URL	Auto-detected based on platform
timeout	HTTP request timeout	10 seconds

---

📖 API Documentation

Base URL

• Development: http://localhost:3000
• Android Emulator: http://10.0.2.2:3000

Endpoints

1. Health Check

GET /api/health

Check if the server is running.

Response:

{
  "status": "OK",
  "message": "PocketPal API is running",
  "timestamp": "2026-04-06T14:35:17.799Z",
  "version": "1.0.0"
}

---

2. Get Monthly Summary

GET /api/summary

Retrieve current month's financial summary.

Auth Required: No

Response:

{
  "success": true,
  "data": {
    "totalIncome": 5800.00,
    "totalExpenses": 291.99,
    "balance": 5508.01,
    "transactionCount": 6,
    "month": "April",
    "year": 2026
  }
}

---

3. Get Transactions

GET /api/transactions

Retrieve all transactions with optional filtering.

Auth Required: No

Query Parameters:

Parameter	Type	Description
type	string	Filter by income or expense
category	string	Filter by category name
limit	number	Limit number of results

Example:

GET /api/transactions?type=expense&limit=10

Response:

{
  "success": true,
  "data": [
    {
      "id": "1",
      "title": "Salary",
      "amount": 5000.00,
      "type": "income",
      "category": "Salary",
      "date": "2026-04-01T10:00:00.000Z",
      "description": "Monthly salary deposit"
    }
  ],
  "count": 6
}

---

4. Add Transaction

POST /api/transactions

Create a new transaction.

Auth Required: No

Request Body:

{
  "title": "Coffee",
  "amount": 5.99,
  "type": "expense",
  "category": "Food",
  "date": "2026-04-06T12:30:00.000Z",
  "description": "Morning coffee"
}

Required Fields: title, amount, type, category
Optional Fields: date, description

Response:

{
  "success": true,
  "data": {
    "id": "7",
    "title": "Coffee",
    "amount": 5.99,
    "type": "expense",
    "category": "Food",
    "date": "2026-04-06T12:30:00.000Z",
    "description": "Morning coffee"
  },
  "message": "Transaction added successfully"
}

---

5. Get Insights

GET /api/insights

Retrieve spending breakdown by category.

Auth Required: No

Response:

{
  "success": true,
  "data": {
    "totalExpenses": 291.99,
    "categoryBreakdown": [
      {
        "category": "Food",
        "amount": 156.00,
        "percentage": "53.4"
      }
    ],
    "topCategory": "Food",
    "categoriesCount": 3
  }
}

---

6. Get Goals

GET /api/goals

Retrieve all savings goals with progress.

Auth Required: No

Response:

{
  "success": true,
  "data": [
    {
      "id": "1",
      "title": "Emergency Fund",
      "targetAmount": 10000.00,
      "currentAmount": 6500.00,
      "deadline": "2026-12-31",
      "category": "Savings",
      "icon": "🚨",
      "progress": "65.0",
      "remaining": 3500.00,
      "daysLeft": 269,
      "status": "active"
    }
  ],
  "count": 3
}

---

Error Responses

All endpoints return errors in this format:

{
  "success": false,
  "message": "Error description",
  "error": "Detailed error (development mode only)"
}

Status Codes:

• 200 - Success
• 201 - Created
• 400 - Bad Request (validation error)
• 404 - Not Found
• 500 - Internal Server Error

---

🧪 Running Tests

Flutter Tests

# Run all tests
flutter test

# Run tests with coverage
flutter test --coverage

# Run specific test file
flutter test test/widget_test.dart

# Run tests in watch mode
flutter test --watch

Backend Tests

Currently, the backend does not have automated tests. To manually test:

# Using curl
curl http://localhost:3000/api/health
curl http://localhost:3000/api/summary
curl -X POST http://localhost:3000/api/transactions \
  -H "Content-Type: application/json" \
  -d '{"title":"Test","amount":10,"type":"expense","category":"Food"}'

# Using a REST client (Postman, Insomnia, etc.)
# Import the endpoints and test manually

Test Structure

test/
├── widget_test.dart          # Sample widget tests
├── unit/                     # Unit tests (to be added)
├── integration/              # Integration tests (to be added)
└── fixtures/                 # Test data fixtures (to be added)

---

🤝 Contributing

Contributions are welcome! Please follow these guidelines:

How to Contribute

1. Fork the repository

   # Click the "Fork" button on GitHub

2. Clone your fork

   git clone https://github.com/YOUR_USERNAME/POCKETPAL.git
   cd POCKETPAL

3. Create a feature branch

   git checkout -b feature/your-feature-name

4. Make your changes

   • Write clean, documented code
   • Follow the existing code style
   • Add tests if applicable

5. Commit your changes

   git add .
   git commit -m "feat: add your feature description"

6. Push to your fork

   git push origin feature/your-feature-name

7. Create a Pull Request

   • Go to the original repository
   • Click "New Pull Request"
   • Select your fork and branch
   • Describe your changes in detail

Coding Standards

Flutter/Dart:

• Follow Effective Dart guidelines
• Use dart format before committing
• Run flutter analyze to check for issues
• Use meaningful variable and function names
• Add doc comments for public APIs

Node.js/JavaScript:

• Use ES6+ syntax
• Use const and let instead of var
• Add JSDoc comments for functions
• Follow consistent indentation (2 spaces)

Branch Naming Conventions

• feature/ - New features (e.g., feature/add-budget-tracking)
• fix/ - Bug fixes (e.g., fix/transaction-overflow)
• refactor/ - Code refactoring (e.g., refactor/api-service)
• docs/ - Documentation updates (e.g., docs/update-readme)
• test/ - Test additions (e.g., test/add-wallet-tests)

Commit Message Format

Follow Conventional Commits:

<type>: <description>

[optional body]

[optional footer]

Types:

• feat: - New feature
• fix: - Bug fix
• docs: - Documentation changes
• style: - Code style changes (formatting, etc.)
• refactor: - Code refactoring
• test: - Adding or updating tests
• chore: - Maintenance tasks

Examples:

feat: add biometric authentication
fix: resolve transaction list overflow
docs: update API documentation
refactor: improve state management with Riverpod

---

📄 License

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

MIT License

Copyright (c) 2026 gopal5587

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.

---

👤 Author

Gopal

• GitHub: @gopal5587
• Repository: POCKETPAL

---

🙏 Acknowledgments

• Flutter Team for the amazing framework
• Riverpod for elegant state management
• FL Chart for beautiful charts
• Express.js for the robust backend framework
• All contributors and users of PocketPal

---

📞 Support

If you encounter any issues or have questions:

1. Check the API Integration Guide
2. Review existing issues
3. Open a new issue with:
   • Clear description of the problem
   • Steps to reproduce
   • Expected vs actual behavior
   • Screenshots (if applicable)
   • Platform and version information

---

🗺️ Roadmap

Planned Features:

• Database integration (PostgreSQL/MongoDB)
• User authentication & authorization
• Cloud sync across devices
• Recurring transactions
• Budget limits with alerts
• Receipt scanning with OCR
• Multi-user household budgets
• Investment tracking
• Bill reminders
• Export to accounting software

Completed Features:

• Full-stack API integration
• Transaction management
• Gamified goals system
• Interactive analytics
• Multi-currency support
• Theme customization
• Data export functionality

---

📸 Screenshots

Add screenshots of your app here once available

---

⭐ Star this repository if you find it helpful!

Made with ❤️ and Flutter