Development Guide

Development Guide

Setup instructions, coding conventions, and workflow for contributing to iTravel.

---

Environment Setup

Option A: Android Studio (Recommended)

1. Install Android Studio (Ladybug or newer)
2. Clone the repository:

   git clone --recurse-submodules https://github.com/HlexNC/iTravel.git

3. Open → select the iTravel/ root directory
4. Wait for Gradle sync to complete
5. Install SDK 34 and Build Tools 36.0.0 if prompted
6. Create or select an emulator (API 26+)
7. Click Run ▶

Option B: VS Code + DevContainer

1. Install Docker Desktop and the Dev Containers extension
2. Open the iTravel/ folder in VS Code
3. Press F1 → Dev Containers: Reopen in Container
4. The container provides JDK 17, Android SDK 36, and Gradle automatically
5. Build from terminal:

   ./gradlew assembleDebug

Note

The DevContainer is configured for headless builds and CI. For on-device debugging, use Android Studio.

---

API Key Configuration

Before running the app, configure the following keys:

// app/src/main/java/com/itravel/app/utils/Constants.java
public static final String UNSPLASH_ACCESS_KEY = "YOUR_KEY";
public static final String WEATHER_API_KEY = "YOUR_KEY";

<!-- app/src/main/AndroidManifest.xml -->
<meta-data
    android:name="com.google.android.geo.API_KEY"
    android:value="YOUR_GOOGLE_MAPS_KEY" />

Warning

Never commit real API keys. For production, migrate keys to local.properties or BuildConfig fields injected at build time.

---

Build Commands

Command	Description
./gradlew assembleDebug	Build debug APK
./gradlew assembleRelease	Build release APK
./gradlew test	Run unit tests
./gradlew connectedAndroidTest	Run instrumented tests
./gradlew lint	Run Android lint checks
./gradlew clean	Clean build outputs

---

Project Conventions

Package Structure

com.itravel.app
├── activities/     # Activity classes (screen hosts)
├── adapters/       # RecyclerView adapters
├── api/            # Retrofit interfaces and client
├── fragments/      # Fragment classes (UI screens)
├── models/         # Data classes and DTOs
└── utils/          # Constants, validators, helpers

Naming Conventions

Type	Convention	Example
Activity	*Activity.java	MainActivity.java
Fragment	*Fragment.java	DiscoverFragment.java
Adapter	*Adapter.java	FeedAdapter.java
Layout (activity)	activity_*.xml	activity_main.xml
Layout (fragment)	fragment_*.xml	fragment_discover.xml
Layout (item)	item_*.xml	item_feed_post.xml
Navigation graph	nav_graph_*.xml	nav_graph_main.xml
DTO model	*Dto.java	WeatherDto.java
Domain model	*.java (no suffix)	Location.java

Code Style

• Java 17 language features are permitted
• Use @NonNull / @Nullable annotations from AndroidX
• ConstraintLayout for all new layouts
• Use ViewBinding or findViewById consistently within a file
• Keep fragment logic in onViewCreated, not onCreateView

---

Git Workflow

Branches

Branch	Purpose
main	Stable, release-ready code
dev	Integration branch for features
feature/*	Individual feature branches
fix/*	Bug fix branches

Commit Messages

Use conventional commits:

feat: add weather overlay to feed cards
fix: GPS validator null check on missing location
docs: update API integration guide
refactor: extract Retrofit client singletons
test: add GPSValidator proximity tests

Submodules

Submodule	Path	Purpose
iTravel-v0	legacy/iTravel-v0	Previous version (read-only reference)
iTravel.wiki	docs/	This documentation

To update submodules:

git submodule update --remote --merge

---

Debugging Tips

Common Issues

Gradle sync fails:

• Ensure JDK 17 is selected in Android Studio → Settings → Build → Gradle → JDK
• Run ./gradlew --stop then re-sync

Map shows blank gray:

• Verify Google Maps API key is set in AndroidManifest.xml
• Check that Maps SDK for Android is enabled in Google Cloud Console
• Ensure the API key's restrictions match your debug SHA-1 fingerprint

Build errors in DevContainer:

• Run ./gradlew --version to verify Gradle is accessible
• Check that ANDROID_SDK_ROOT is set to /opt/android-sdk

Useful ADB Commands

# List connected devices
adb devices

# Install debug APK
adb install app/build/outputs/apk/debug/app-debug.apk

# View app logs
adb logcat -s "iTravel"

# Clear app data
adb shell pm clear com.itravel.app