Skip to content

Home

Jump to bottom
Hlex Helftd edited this page Feb 10, 2026 · 5 revisions

🌍 iTravel

A location-aware Android travel companion — discover, review, and share places with fellow travelers

GitHub Repository Android 14 Java 17 Android Studio Gradle 8.13

🚀 Quick Start

Tip

Recommended IDE: Android Studio (Ladybug or newer) for running, testing, and debugging. VS Code with Java extensions works for editing.

Prerequisites

  • Android Studio Ladybug+ (or VS Code with Java Extension Pack)
  • JDK 17 (bundled with Android Studio)
  • Android SDK 34 with Build Tools 36.0.0

Clone & Run

# Clone with submodules
git clone --recurse-submodules https://github.com/HlexNC/iTravel.git
cd iTravel

# Open in Android Studio → Run on emulator or device

Command-Line Build

./gradlew assembleDebug

DevContainer (CI / Headless Builds)

# VS Code: Reopen in Container (requires Docker)
# Or manually:
docker build -t itravel-dev .devcontainer/
docker run --rm -v "$(pwd)":/workspaces/iTravel itravel-dev ./gradlew assembleDebug

Important

API Keys Required — Before running, add your keys in app/.../utils/Constants.java:

🏗️ Architecture Overview

graph TB
    subgraph "Presentation Layer"
        A[Activities]
        B[Fragments]
        C[Adapters]
    end

    subgraph "Navigation"
        D[Jetpack Navigation<br/>Auth Graph · Main Graph]
    end

    subgraph "Data Layer"
        E[Retrofit API Clients]
        F[Room Database]
        G[SharedPreferences<br/>Encrypted]
    end

    subgraph "External Services"
        H[REST Countries API]
        I[Unsplash Photos API]
        J[OpenWeatherMap API]
        K[Google Maps SDK]
    end

    A --> D
    D --> B
    B --> C
    B --> E
    B --> F
    B --> G
    E --> H
    E --> I
    E --> J
    B --> K
Loading
Layer Components Purpose
Activities SplashActivity, AuthActivity, MainActivity, LocationDetailActivity Screen hosts and lifecycle owners
Fragments WelcomeFragment, LoginFragment, RegisterFragment, DiscoverFragment, FeedFragment, SearchFragment, ProfileFragment, AddReviewFragment UI screens within navigation graphs
API RetrofitClient, CountriesApi, UnsplashApi, WeatherApi REST networking via Retrofit + Gson
Storage Room (local DB), EncryptedSharedPreferences Offline data and secure credentials
Maps Google Maps SDK + Fused Location Provider Map display and GPS validation

✨ Features

🎯 Core Functionality

  • Discover Map: Interactive Google Maps view with location markers and categories
  • Travel Feed: Instagram-style card feed with photos, weather overlays, and likes
  • Location Reviews: GPS-verified reviews with photo attachments and star ratings
  • User Authentication: Login / Register flow with encrypted credential storage
  • Country Explorer: Browse countries via REST Countries API with flag imagery

🛡️ Technical Highlights

  • GPS Validation: Reviews require physical proximity to the location (GPSValidator)
  • Encrypted Storage: androidx.security:security-crypto for sensitive data
  • Image Loading: Glide for efficient image caching and display
  • Navigation Component: Two nav graphs (auth + main) with bottom navigation
  • Material Design 3: Themed with Theme.Material3.DayNight.NoActionBar

📱 User Experience

  • Splash Screen: Branded launch with auto-transition to auth
  • Bottom Navigation: Discover · Feed · Search · Profile
  • Card-Based Feed: CardView + RecyclerView with gradient overlays
  • Responsive Layouts: ConstraintLayout throughout

📁 Project Structure

iTravel/
├── 📄 build.gradle                 # Root build config (AGP 8.13.2)
├── 📄 settings.gradle              # Module includes + repositories
├── 📄 gradle.properties            # JVM and AndroidX settings
├── 📁 .devcontainer/               # VS Code DevContainer (Docker)
│   ├── Dockerfile                  # Ubuntu 22.04 + JDK 17 + Android SDK
│   └── devcontainer.json           # Container configuration
├── 📁 app/                         # Application module
│   ├── build.gradle                # App dependencies and SDK config
│   └── 📁 src/main/
│       ├── AndroidManifest.xml     # Permissions and activity declarations
│       ├── 📁 java/.../activities/ # Activity classes
│       ├── 📁 java/.../fragments/  # Fragment classes
│       ├── 📁 java/.../adapters/   # RecyclerView adapters
│       ├── 📁 java/.../api/        # Retrofit interfaces + client
│       ├── 📁 java/.../models/     # Data models and DTOs
│       ├── 📁 java/.../utils/      # Constants, validation, GPS
│       └── 📁 res/                 # Layouts, navigation, drawables, values
├── 📁 docs/                        # Project documentation (wiki submodule)
└── 📁 legacy/                      # Previous version (iTravel-v0 submodule)

🧰 Tech Stack

Category Technology Version
Language Java 17
Build System Gradle (Groovy DSL) 8.13
Android Gradle Plugin AGP 8.13.2
Min SDK Android 8.0 API 26
Target SDK Android 14 API 34
UI Toolkit Material Design 3 1.11.0
Navigation Jetpack Navigation 2.7.7
Networking Retrofit 2 + OkHttp 2.9.0 / 4.12.0
Image Loading Glide 4.16.0
Database Room 2.6.1
Maps Google Maps SDK 18.2.0
Location Fused Location Provider 21.1.0
Security EncryptedSharedPreferences 1.1.0-alpha06
Testing JUnit 4 + Espresso 4.13.2 / 3.5.1

🧪 Testing

# Unit tests
./gradlew test

# Instrumented tests (requires emulator or device)
./gradlew connectedAndroidTest

Current test coverage includes:

  • GPSValidatorTest — proximity validation for review submission
  • Additional unit and integration tests (planned)

🔧 Development Setup

Android Studio (Primary)

  1. Open → Select the iTravel/ root directory
  2. Sync Gradle — Android Studio will download dependencies automatically
  3. Run → Select an emulator (API 26+) or connected device
  4. Debug → Set breakpoints and use the built-in debugger

VS Code (Editing + DevContainer)

  1. Install extensions: vscjava.vscode-java-pack, redhat.java
  2. Open the project folder
  3. Optional: Reopen in Container for a fully configured build environment

API Key Configuration

Key File Field
Unsplash Constants.java UNSPLASH_ACCESS_KEY
OpenWeatherMap Constants.java WEATHER_API_KEY
Google Maps AndroidManifest.xml com.google.android.geo.API_KEY

Warning

Security: Do not commit API keys to version control. Use local.properties or environment variables for production builds.

🎨 Design System

Token Color Hex Usage
teal_primary 🟩 #1E7B7E Primary brand, app bars
teal_secondary 🟩 #2A9D8F Secondary accents
orange_accent 🟧 #F4A261 CTAs, highlights
coral_action 🟥 #E76F51 Destructive actions
dark_slate ⬛ #264653 Dark backgrounds, text
off_white ⬜ #F1FAEE Light backgrounds

📄 Documentation

Page Description
Home This page — project overview
Architecture Detailed architecture and data flow
API-Integration External API setup and usage
Development-Guide Setup, conventions, and workflow

🎓 Academic Project

Note

University Project: Developed as part of Media Technology at Deggendorf Institute of Technology (DIT).

📄 License

Licensed under the GNU General Public License v3.0 — see the LICENSE file for details.

Built with ❤️ for travelers, by travelers
Von Travelern für Traveler

iTravel — Von Travelern für Traveler · GitHub · Deggendorf Institute of Technology

📖 iTravel Wiki

Links

Clone this wiki locally