GroupLedger - Travel & Expense Tracking Android App

A modern Android application combining expense tracking (Ledger) with AI-powered travel itinerary planning, built with Kotlin and Jetpack Compose.

Features

💰 Ledger (Expense Tracking)

• Group Management: Create and manage expense groups with multiple members
• Smart Expense Splitting:
  • Equal split - automatically divides expenses evenly
  • Manual split - customize amounts for each member
• Balance Tracking: Real-time calculation of who owes whom
• Expense History: View all group expenses with details

🗺️ Itinerary (Travel Planning)

• AI-Powered Generation: Describe your travel needs and let AI create a personalized itinerary
• Itinerary Management: View and organize your travel plans
• Detailed Planning: See locations, times, and descriptions for each itinerary item

🎨 Modern UI/UX

• Material Design 3
• Dark/Light theme support
• Pull-to-refresh
• Bottom navigation
• Smooth animations

Tech Stack

• Language: Kotlin
• UI: Jetpack Compose (Material 3)
• Architecture: MVVM (Model-View-ViewModel)
• Dependency Injection: Hilt
• Networking: Retrofit 2 + OkHttp 3
• JSON: Moshi
• Navigation: Navigation Compose
• Storage: DataStore (Preferences)
• Async: Kotlin Coroutines + Flow

Project Structure

app/src/main/java/cc/jingtianhu/groupledger/
├── data/
│   ├── api/              # API definitions and DTOs
│   └── repository/       # Data repositories
├── di/                   # Dependency injection modules
├── features/
│   ├── auth/            # Login & Registration
│   ├── itinerary/       # Travel itinerary features
│   │   ├── list/
│   │   ├── detail/
│   │   └── generate/
│   └── ledger/          # Expense tracking features
│       ├── list/
│       ├── detail/
│       ├── balance/
│       ├── add_expense/
│       └── add_group/
├── navigation/          # Navigation setup
├── ui/theme/           # Theme and styling
└── MainActivity.kt     # App entry point

Setup & Installation

Prerequisites

• Android Studio Hedgehog or newer
• JDK 17
• Android SDK (API level 26+)
• Backend API running (see backend setup)

Backend Setup

1. Ensure your Django backend is running on localhost:8000
2. Update BASE_URL in di/NetworkModule.kt if using a different address:

   private const val BASE_URL = "http://10.0.2.2:8000/" // For emulator
   // or
   private const val BASE_URL = "http://YOUR_IP:8000/" // For physical device

Build & Run

1. Clone the repository
2. Open project in Android Studio
3. Sync Gradle dependencies
4. Run on emulator or device

API Endpoints Used

Authentication

• POST /api/register/ - User registration
• POST /api/login/ - User login

Ledger

• GET /api/groups/ - List groups
• POST /api/groups/ - Create group
• GET /api/groups/{id}/ - Group details
• GET /api/groups/{id}/balances/ - Group balances
• POST /api/expenses/ - Create expense

Itinerary

• GET /api/itineraries/ - List itineraries
• GET /api/itineraries/{id}/ - Itinerary details
• POST /api/itineraries/generate/ - AI generate itinerary
• POST /api/itinerary-items/ - Create itinerary item

User Guide

Getting Started

1. Register: Create an account with username and password
2. Login: Sign in to access your data

Using Ledger

1. Create a Group: Tap the + button on Groups screen
2. Add Members: Enter member user IDs (comma-separated)
3. Add Expenses:
   • Tap + in a group
   • Enter description and amount
   • Select who paid
   • Choose split type (Equal or Manual)
   • Review split amounts
   • Create expense
4. View Balances: Tap "View Balances" button in group detail

Using Itinerary

1. Generate Itinerary:
   • Tap + on Itinerary screen
   • Enter destination (e.g., "Tokyo")
   • Describe your needs (e.g., "3 days, interested in food and culture")
   • Tap "Generate Itinerary"
   • Wait for AI to create your plan
2. View Details: Tap any itinerary to see full schedule

Configuration

Network Timeout

Modify in NetworkModule.kt:

OkHttpClient.Builder()
    .connectTimeout(30, TimeUnit.SECONDS)
    .readTimeout(30, TimeUnit.SECONDS)
    .writeTimeout(30, TimeUnit.SECONDS)

Logging

HTTP logging is enabled by default. To disable in production:

val logging = HttpLoggingInterceptor()
logging.setLevel(HttpLoggingInterceptor.Level.NONE) // Change to NONE

Known Issues

See KNOWN_ISSUES.md for detailed list of known bugs and limitations.

Critical Limitations:

1. Member IDs must be entered manually when creating groups (no user search)
2. Dummy IDs used in AddExpense (will cause API errors)
3. No logout function
4. No input validation on some fields

Implementation Status

See IMPLEMENTATION_SUMMARY.md for complete implementation details.

✅ Completed Features (80%)

• Authentication (login/register)
• Group management
• Expense creation with splits
• Balance viewing
• Itinerary generation (AI)
• Itinerary viewing
• Bottom navigation
• Pull-to-refresh

🚧 Pending Features (20%)

• User search for groups
• Receipt image upload
• Comprehensive testing
• Production-ready error handling
• Manual itinerary creation
• Expense editing/deletion

Testing

Run Unit Tests

./gradlew test

Run Instrumentation Tests

./gradlew connectedAndroidTest

Note: Tests need to be written. See testing strategy in blueprint.

Contributing

Code Style

• Follow Kotlin coding conventions
• Use meaningful variable names
• Add KDoc comments for public functions
• Keep composables small and focused

Branching Strategy

• main - Production-ready code
• develop - Development branch
• feature/* - Feature branches

Dependencies

Key dependencies (see app/build.gradle.kts for versions):

• androidx.compose.material3 - Material Design 3
• androidx.navigation:navigation-compose - Navigation
• com.google.dagger:hilt-android - Dependency injection
• com.squareup.retrofit2:retrofit - HTTP client
• com.squareup.moshi:moshi-kotlin - JSON parsing
• androidx.datastore:datastore-preferences - Local storage

License

[Add your license here]

Authors

[Add your name here]

Acknowledgments

• Blueprint design inspired by modern travel and expense tracking apps
• AI itinerary generation powered by backend AI service
• Material Design 3 guidelines

Support

For issues and questions:

• Check KNOWN_ISSUES.md
• Review IMPLEMENTATION_SUMMARY.md
• See ITEMIZED_OCR_IMPLEMENTATION_GUIDE.md for OCR receipt scanning feature
• See AUTO_REFRESH_FIX.md for auto-refresh implementation details
• Create a GitHub issue

---

Built with ❤️ using Kotlin and Jetpack Compose