🌍 Travelo

🧳 Travel & Code! A modern travel guide app built to inspire wanderlust and showcase clean Android development

Discover amazing destinations • Learn modern Android development • Explore the world

---

✨ About

Travelo is more than just a travel app—it's a learning playground for modern Android development! Built with the latest technologies and best practices, this app demonstrates how to create beautiful, performant, and maintainable Android applications while helping users discover incredible travel destinations worldwide.

Whether you're a developer looking to learn clean architecture patterns or a traveler seeking your next adventure, this app has something for you!

🎨 Design Inspiration

The UI is inspired by the gorgeous "Aspen Travel App Exploration- Mobile App Design" by Nickelfox Design that showcases modern travel app design patterns with:

• Clean, minimalist interface
• Beautiful imagery and typography
• Intuitive navigation patterns
• Mobile-first responsive design

🏗️ Architecture

Built following Clean Architecture principles with MVVM pattern:

📱 Presentation Layer
├── 🎨 UI Components (Jetpack Compose)
├── 📄 Screens & Navigation  
└── 🧠 ViewModels & State Management

💼 Domain Layer
├── 🔄 Use Cases
├── 📋 Repository Interfaces
└── 🏷️ Domain Models

💾 Data Layer
├── 🌐 Remote Data Sources (TripAdvisor API + OpenWeatherMap API)
├── 💿 Local Data Source (Room Database)
└── 🗄️ Repository Implementation

🚀 Features

🔍 Smart Discovery

• Browse destinations by categories
• Location-based recommendations with GPS integration
• Popular and trending spots
• Advanced search functionality with category filtering

📍 Intelligent Location Services

• GPS Location Detection - Automatically find your current location
• City Search & Selection - Search for any city worldwide
• Geocoding & Reverse Geocoding - Convert between addresses and coordinates
• Weather Integration - Get current weather for any location

🗺️ Rich Location Data

• Detailed destination information
• High-quality photos and galleries
• Reviews and ratings
• Geographic coordinates and maps

📱 Modern UI/UX

• Material 3 Design System
• Smooth animations and transitions
• Dark/Light theme support
• Responsive layouts for all screen sizes
• Native Splash Screen with proper branding

⚡ Performance & Reliability

• Offline-First Architecture - Works seamlessly without internet
• Efficient image loading and caching
• Error handling with retry mechanisms
• Optimized for battery and data usage

🧪 Quality Assurance

• Comprehensive Unit Testing - ViewModels, Repositories, and business logic
• UI Testing - Composable component testing with test automation
• Integration Testing - End-to-end user flow validation
• MockK Integration - Advanced mocking for isolated component testing
• Coroutine Testing - Proper async code testing with TestDispatcher
• Hilt Testing - Dependency injection testing with test doubles

🛠️ Tech Stack

Core Framework

• Kotlin - Modern, concise, and safe programming language
• Jetpack Compose - Declarative UI toolkit for native Android
• Material 3 - Latest Material Design components

Architecture Components

• MVVM Pattern - Separation of concerns and testability
• Clean Architecture - Maintainable and scalable code structure
• Offline-First Architecture - Seamless user experience without connectivity
• Dagger Hilt - Dependency injection for cleaner code
• Navigation Compose - Type-safe navigation between screens

Data & Networking

• Retrofit - Type-safe HTTP client for API communication
• Room Database - Local data persistence and caching
• DataStore Preferences - Modern data storage solution for user preferences
• Gson - JSON serialization and deserialization
• OkHttp Logging Interceptor - Network request/response logging

Location & Services

• Google Play Location Services - Accurate GPS positioning
• Core SplashScreen - Native Android 12+ splash screen implementation

UI & Media

• Coil Compose - Fast and lightweight image loading library
• Material Icons Extended - Comprehensive icon library
• Custom Animations - Smooth and delightful user interactions

Testing & Quality

• JUnit 4 - Unit testing framework
• MockK - Mocking library for Kotlin
• Truth - Fluent assertion library by Google
• Compose UI Testing - Automated UI component testing
• Coroutines Test - Testing support for coroutines and flows
• Hilt Testing - Dependency injection testing utilities
• Espresso - UI testing framework for integration tests

Development Tools

• KSP (Kotlin Symbol Processing) - Faster annotation processing
• Gradle Version Catalogs - Centralized dependency management

🌐 Data Sources

TripAdvisor API

Provides comprehensive travel data including:

• 🏨 Hotels and accommodations
• 🍽️ Restaurants and dining
• 🎯 Attractions and activities
• 📍 Location details and reviews
• 📊 Real-time ratings and feedback

OpenWeatherMap API ⭐

A fantastic completely free weather service (unlike TripAdvisor's paid tiers!) providing:

• 🌤️ Current weather conditions
• 🌍 City and country search with geocoding
• 🗺️ Reverse geocoding for coordinates
• 📍 Location-based weather data
• 🆓 100% Free - No hidden costs or usage limits for basic features!

Special thanks to OpenWeatherMap for providing an excellent free service that makes location-based features accessible to all developers!

🎥 App Demo

📱 Download App Demo Video (5.98 MB)
See Travelo in action: location discovery, search, and detailed views

📱 Screenshots

Core Features

Location & Search

App States

Top row: Home screen with Nature category & detailed location view
Middle row: Smart location selection with GPS & advanced search with filtering
Bottom row: Empty state handling & clean initial search interface

🚀 Getting Started

Prerequisites

• Android Studio Hedgehog | 2023.1.1 or newer
• JDK 21 or higher
• Android SDK with API level 24+
• TripAdvisor API Key (see setup instructions below)
• OpenWeatherMap API Key (see setup instructions below)

Installation

1. Clone the repository

   git clone https://github.com/Farajialireza82/VacationApp.git
   cd VacationApp

2. Get your TripAdvisor API key

   • Visit TripAdvisor Developer Portal
   • Create an account and generate an API key

3. Get your OpenWeatherMap API key

   • Visit OpenWeatherMap API
   • Create a free account and generate an API key
   • Enjoy their completely free tier! 🎉

4. Configure API keys

   • Add your API keys to gradle.properties:

   TRIP_ADVISOR_API_KEY=your_trip_advisor_key_here
   OPEN_WEATHER_MAP_API_KEY=your_open_weather_map_key_here

5. Open in Android Studio

   • Open Android Studio
   • Select "Open an existing project"
   • Navigate to the cloned directory and open it

6. Build and Run

   • Sync the project with Gradle files
   • Run the app on an emulator or physical device

🧪 Testing

Testing infrastructure is currently being developed:

# Unit tests
./gradlew test

# Instrumented tests
./gradlew connectedAndroidTest

📂 Project Structure

app/
├── src/main/kotlin/com/cromulent/vacationapp/
│   ├── data/           # Data layer implementation
│   │   ├── local/      # Room database, DAOs
│   │   ├── remote/     # API services, DTOs
│   │   └── repository/ # Repository implementations
│   ├── domain/         # Business logic layer
│   │   └── repository/ # Repository interfaces
│   ├── model/          # Data models and entities
│   ├── presentation/   # UI layer
│   │   ├── components/ # Reusable UI components
│   │   ├── home/       # Home screen and components
│   │   ├── location/   # Location selector screen
│   │   ├── search/     # Search screen with filtering
│   │   ├── navigation/ # Navigation setup
│   │   └── theme/      # App theming and styling
│   └── util/           # Utility classes and constants

🤝 Contributing

We love contributions! Whether you're fixing bugs, adding features, or improving documentation, your help makes this project better.

How to Contribute

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

Development Guidelines

• Follow Kotlin coding conventions
• Write unit tests for new features
• Update documentation as needed
• Use meaningful commit messages

📄 License

This project is open source and available under the MIT License.

🙏 Acknowledgments

• Nickelfox Design - For the beautiful "Aspen Travel App Exploration" design inspiration
• TripAdvisor - For providing comprehensive travel data
• OpenWeatherMap - For their amazing completely free weather and geocoding services! 🌟
• Android Developer Community - For excellent documentation and resources
• Jetpack Compose Community - For pushing the boundaries of Android UI development

📞 Contact & Support

• Issues: GitHub Issues
• Email: farajialireza82@gmail.com

---

Made with ❤️ for travelers and developers worldwide

Happy coding and safe travels! 🌍✈️