# shakibim/locationtracker-android-app architecture

> Architecture diagram of the GitHub repository shakibim/locationtracker-android-app, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/shakibim/locationtracker-android-app
- Repository: https://github.com/shakibim/locationtracker-android-app

## Overview

1. **Project shape**
   - This is a single-module Android app (`app`) written in **Java** with **XML** layouts and Gradle Kotlin build scripts.
   - The architecture is client-only: there is **no backend service** in the repo. Core state lives on the device.

2. **High-level flow**
   - The app starts with an onboarding/auth path: **GetStarted → SignIn / SignUp → MainActivity**.
   - After login, the user lands in the main shell, which hosts the app’s functional screens: **Home**, **History**, and **Profile**.

3. **Main navigation shell**
   - `MainActivity` is the container for the authenticated experience.
   - `bottom_nav_menu.xml` and the fragment classes indicate a **bottom-navigation, fragment-based UI** rather than multiple independent screens.
   - `HomeFragment`, `HistoryFragment`, and `ProfileFragment` are the primary feature areas.

4. **Authentication and session boundary**
   - `SignUp.java` and `SignIn.java` manage account creation and login.
   - `UserDatabaseHelper.java` stores user records locally in **SQLite**.
   - The README says login state is persisted with **SharedPreferences**, which acts as the session boundary that decides whether to show the auth flow or the main app.

5. **Location tracking pipeline**
   - `HomeFragment` is the control center for tracking, including the on/off switch mentioned in the README.
   - `LocationService.java` is the background component responsible for collecting device GPS location at intervals.
   - The app stores location snapshots every five minutes with timestamp metadata, and shows a toast notification when a reading is saved.

6. **Local data persistence**
   - `LocationDatabaseHelper.java` is the storage layer for tracked location history.
   - `LocationModel.java` represents a single location record, likely including latitude, longitude, date/time, and possibly an identifier.
   - This makes the app **offline-first**: saved data remains available without network access.

7. **History browsing and list presentation**
   - `HistoryFragment.java` displays stored tracking records.
   - `LocationAdapter.java` binds `LocationModel` items into the list UI defined in `item_location.xml`.
   - The list is the read-side of the location database, separated from the write-side handled by the service.

8. **Details view**
   - `ViewDetailsLocation.java` and `activity_view_details_location.xml` provide a per-record detail screen.
   - This is the drill-down from history into a single saved location entry, probably used to inspect coordinates and timestamp more closely.

9. **Profile area**
   - `ProfileFragment.java` is the user/account screen inside the authenticated shell.
   - Given the presence of shared session state and auth screens, this fragment likely summarizes the current user and offers logout or account-related actions.

10. **UI structure and assets**
    - The repository uses standard Android resource separation: layouts, drawables, menus, themes, dimens, and strings.
    - Material-style icons and themed backgrounds suggest a **Material Components** UI layered on top of native Android views.

11. **External integrations noted in the README**
    - The README documents optional/adjacent integrations with **OSMDroid/OpenStreetMap**, **Nominatim** for reverse geocoding, and **Open-Meteo** for weather.
    - These would sit at the presentation edge of the location screens, enriching raw GPS coordinates with map, place-name, or weather context if those features are enabled.

12. **Architectural boundaries**
    - The main separation is between:
      - **UI layer**: activities/fragments/adapters/layouts
      - **State and session layer**: SharedPreferences + auth flow
      - **Persistence layer**: SQLite helpers and models
      - **Background capture layer**: `LocationService`
    - The app’s data moves from GPS → service → SQLite → history adapter/details screen, while authentication moves from sign-in/up → shared session → main navigation.

Main entry points: [`LocationTracker/app/src/main/java/com/example/locationtracker/HistoryFragment.java`](https://github.com/shakibim/locationtracker-android-app/blob/main/LocationTracker/app/src/main/java/com/example/locationtracker/HistoryFragment.java) (History), [`LocationTracker/app/src/main/java/com/example/locationtracker/LocationService.java`](https://github.com/shakibim/locationtracker-android-app/blob/main/LocationTracker/app/src/main/java/com/example/locationtracker/LocationService.java) (Location Service), [`LocationTracker/app/src/main/res/menu/bottom_nav_menu.xml`](https://github.com/shakibim/locationtracker-android-app/blob/main/LocationTracker/app/src/main/res/menu/bottom_nav_menu.xml) (Bottom Nav), [`LocationTracker/app/src/main/java/com/example/locationtracker/MainActivity.java`](https://github.com/shakibim/locationtracker-android-app/blob/main/LocationTracker/app/src/main/java/com/example/locationtracker/MainActivity.java) (Main Activity)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["UI Shell"]
  node_get_started["Get Started<br/>entry activity<br/>[GetStarted.java]"]
  node_main_activity["Main Activity<br/>shell activity<br/>[MainActivity.java]"]
  node_profile_fragment["Profile<br/>account fragment"]
end

subgraph group_auth["Auth & Session"]
  node_sign_in["Sign In<br/>auth activity<br/>[SignIn.java]"]
  node_sign_up["Sign Up<br/>auth activity<br/>[SignUp.java]"]
  node_session_state[("Session State<br/>shared prefs")]
  node_user_db[("User DB<br/>sqlite helper")]
end

subgraph group_tracking["Location Capture"]
  node_home_fragment["Home<br/>tracking fragment<br/>[HomeFragment.java]"]
  node_location_service["Location Service<br/>background service"]
  node_gps_source(("GPS Source<br/>device location"))
end

subgraph group_data["Local Data"]
  node_location_db[("Location DB<br/>sqlite helper")]
  node_location_model["Location Model<br/>record model<br/>[LocationModel.java]"]
  node_history_fragment["History<br/>list fragment"]
  node_location_adapter["Location Adapter<br/>list adapter"]
  node_details_activity["Location Details<br/>detail activity"]
end

subgraph group_resources["Resources"]
  node_bottom_nav["Bottom Nav<br/>menu"]
  node_home_layout["Home Layout<br/>[home_fragment.xml]"]
  node_history_layout["History Layout"]
  node_details_layout["Details Layout"]
end

node_get_started -->|"entry"| node_sign_in
node_get_started -->|"new user"| node_sign_up
node_sign_up -->|"stores user"| node_user_db
node_sign_in -->|"verifies user"| node_user_db
node_sign_in -->|"sets login"| node_session_state
node_sign_up -->|"starts session"| node_session_state
node_session_state -->|"opens shell"| node_main_activity
node_main_activity -->|"hosts nav"| node_bottom_nav
node_bottom_nav -->|"tab"| node_home_fragment
node_bottom_nav -->|"tab"| node_history_fragment
node_bottom_nav -->|"tab"| node_profile_fragment
node_home_fragment -->|"starts/stops"| node_location_service
node_location_service -->|"reads"| node_gps_source
node_location_service -->|"writes snapshot"| node_location_db
node_location_service -->|"creates record"| node_location_model
node_location_db -->|"feeds history"| node_history_fragment
node_history_fragment -->|"binds list"| node_location_adapter
node_location_adapter -->|"renders"| node_location_model
node_history_fragment -->|"opens detail"| node_details_activity
node_details_activity -->|"uses layout"| node_details_layout
node_home_fragment -->|"uses layout"| node_home_layout
node_history_fragment -->|"uses layout"| node_history_layout
node_main_activity -->|"contains"| node_profile_fragment

click node_get_started "https://github.com/shakibim/locationtracker-android-app/blob/main/LocationTracker/app/src/main/java/com/example/locationtracker/GetStarted.java"
click node_sign_in "https://github.com/shakibim/locationtracker-android-app/blob/main/LocationTracker/app/src/main/java/com/example/locationtracker/SignIn.java"
click node_sign_up "https://github.com/shakibim/locationtracker-android-app/blob/main/LocationTracker/app/src/main/java/com/example/locationtracker/SignUp.java"
click node_user_db "https://github.com/shakibim/locationtracker-android-app/blob/main/LocationTracker/app/src/main/java/com/example/locationtracker/UserDatabaseHelper.java"
click node_main_activity "https://github.com/shakibim/locationtracker-android-app/blob/main/LocationTracker/app/src/main/java/com/example/locationtracker/MainActivity.java"
click node_bottom_nav "https://github.com/shakibim/locationtracker-android-app/blob/main/LocationTracker/app/src/main/res/menu/bottom_nav_menu.xml"
click node_home_fragment "https://github.com/shakibim/locationtracker-android-app/blob/main/LocationTracker/app/src/main/java/com/example/locationtracker/HomeFragment.java"
click node_location_service "https://github.com/shakibim/locationtracker-android-app/blob/main/LocationTracker/app/src/main/java/com/example/locationtracker/LocationService.java"
click node_location_db "https://github.com/shakibim/locationtracker-android-app/blob/main/LocationTracker/app/src/main/java/com/example/locationtracker/LocationDatabaseHelper.java"
click node_location_model "https://github.com/shakibim/locationtracker-android-app/blob/main/LocationTracker/app/src/main/java/com/example/locationtracker/LocationModel.java"
click node_history_fragment "https://github.com/shakibim/locationtracker-android-app/blob/main/LocationTracker/app/src/main/java/com/example/locationtracker/HistoryFragment.java"
click node_location_adapter "https://github.com/shakibim/locationtracker-android-app/blob/main/LocationTracker/app/src/main/java/com/example/locationtracker/LocationAdapter.java"
click node_details_activity "https://github.com/shakibim/locationtracker-android-app/blob/main/LocationTracker/app/src/main/java/com/example/locationtracker/ViewDetailsLocation.java"
click node_profile_fragment "https://github.com/shakibim/locationtracker-android-app/blob/main/LocationTracker/app/src/main/java/com/example/locationtracker/ProfileFragment.java"
click node_home_layout "https://github.com/shakibim/locationtracker-android-app/blob/main/LocationTracker/app/src/main/res/layout/home_fragment.xml"
click node_history_layout "https://github.com/shakibim/locationtracker-android-app/blob/main/LocationTracker/app/src/main/res/layout/history_fragment.xml"
click node_details_layout "https://github.com/shakibim/locationtracker-android-app/blob/main/LocationTracker/app/src/main/res/layout/activity_view_details_location.xml"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_get_started,node_main_activity,node_profile_fragment toneBlue
class node_sign_in,node_sign_up,node_session_state,node_user_db toneAmber
class node_home_fragment,node_location_service,node_gps_source toneMint
class node_location_db,node_location_model,node_history_fragment,node_location_adapter,node_details_activity toneRose
class node_bottom_nav,node_home_layout,node_history_layout,node_details_layout toneIndigo
```

## Components

### UI Shell

Entry, navigation, and screens

- [Get Started](https://github.com/shakibim/locationtracker-android-app/blob/main/LocationTracker/app/src/main/java/com/example/locationtracker/GetStarted.java): entry activity · Launch screen that routes into authentication or the app shell · `LocationTracker/app/src/main/java/com/example/locationtracker/GetStarted.java`
- [Main Activity](https://github.com/shakibim/locationtracker-android-app/blob/main/LocationTracker/app/src/main/java/com/example/locationtracker/MainActivity.java): shell activity · Authenticated container that hosts bottom navigation and fragments · `LocationTracker/app/src/main/java/com/example/locationtracker/MainActivity.java`
- [Profile](https://github.com/shakibim/locationtracker-android-app/blob/main/LocationTracker/app/src/main/java/com/example/locationtracker/ProfileFragment.java): account fragment · Authenticated user screen for profile and logout actions · `LocationTracker/app/src/main/java/com/example/locationtracker/ProfileFragment.java`

### Auth & Session

Login, signup, and persisted session state

- [Sign In](https://github.com/shakibim/locationtracker-android-app/blob/main/LocationTracker/app/src/main/java/com/example/locationtracker/SignIn.java): auth activity · Login screen that validates existing users · `LocationTracker/app/src/main/java/com/example/locationtracker/SignIn.java`
- [Sign Up](https://github.com/shakibim/locationtracker-android-app/blob/main/LocationTracker/app/src/main/java/com/example/locationtracker/SignUp.java): auth activity · Account creation screen for new users · `LocationTracker/app/src/main/java/com/example/locationtracker/SignUp.java`
- **Session State**: shared prefs · Stored login state that decides whether to show auth or the main app
- [User DB](https://github.com/shakibim/locationtracker-android-app/blob/main/LocationTracker/app/src/main/java/com/example/locationtracker/UserDatabaseHelper.java): sqlite helper · Local SQLite store for user records · `LocationTracker/app/src/main/java/com/example/locationtracker/UserDatabaseHelper.java`

### Location Capture

Background GPS capture and record flow

- [Home](https://github.com/shakibim/locationtracker-android-app/blob/main/LocationTracker/app/src/main/java/com/example/locationtracker/HomeFragment.java): tracking fragment · Control center for tracking on/off and live capture controls · `LocationTracker/app/src/main/java/com/example/locationtracker/HomeFragment.java`
- [Location Service](https://github.com/shakibim/locationtracker-android-app/blob/main/LocationTracker/app/src/main/java/com/example/locationtracker/LocationService.java): background service · Collects device GPS location at intervals · `LocationTracker/app/src/main/java/com/example/locationtracker/LocationService.java`
- **GPS Source**: device location · Underlying device location provider used by the service

### Local Data

SQLite-backed storage and list binding

- [Location DB](https://github.com/shakibim/locationtracker-android-app/blob/main/LocationTracker/app/src/main/java/com/example/locationtracker/LocationDatabaseHelper.java): sqlite helper · Local history store for tracked location snapshots · `LocationTracker/app/src/main/java/com/example/locationtracker/LocationDatabaseHelper.java`
- [Location Model](https://github.com/shakibim/locationtracker-android-app/blob/main/LocationTracker/app/src/main/java/com/example/locationtracker/LocationModel.java): record model · Single saved location entry with coordinates and timestamp · `LocationTracker/app/src/main/java/com/example/locationtracker/LocationModel.java`
- [History](https://github.com/shakibim/locationtracker-android-app/blob/main/LocationTracker/app/src/main/java/com/example/locationtracker/HistoryFragment.java): list fragment · Browse stored tracking records · `LocationTracker/app/src/main/java/com/example/locationtracker/HistoryFragment.java`
- [Location Adapter](https://github.com/shakibim/locationtracker-android-app/blob/main/LocationTracker/app/src/main/java/com/example/locationtracker/LocationAdapter.java): list adapter · Binds saved location models into the history list UI · `LocationTracker/app/src/main/java/com/example/locationtracker/LocationAdapter.java`
- [Location Details](https://github.com/shakibim/locationtracker-android-app/blob/main/LocationTracker/app/src/main/java/com/example/locationtracker/ViewDetailsLocation.java): detail activity · Drill-down view for a single saved location entry · `LocationTracker/app/src/main/java/com/example/locationtracker/ViewDetailsLocation.java`

### Resources

Key layouts and navigation menu

- [Bottom Nav](https://github.com/shakibim/locationtracker-android-app/blob/main/LocationTracker/app/src/main/res/menu/bottom_nav_menu.xml): menu · Navigation menu for the main shell tabs · `LocationTracker/app/src/main/res/menu/bottom_nav_menu.xml`
- [Home Layout](https://github.com/shakibim/locationtracker-android-app/blob/main/LocationTracker/app/src/main/res/layout/home_fragment.xml): layout · Screen layout for the tracking dashboard · `LocationTracker/app/src/main/res/layout/home_fragment.xml`
- [History Layout](https://github.com/shakibim/locationtracker-android-app/blob/main/LocationTracker/app/src/main/res/layout/history_fragment.xml): layout · Screen layout for location history · `LocationTracker/app/src/main/res/layout/history_fragment.xml`
- [Details Layout](https://github.com/shakibim/locationtracker-android-app/blob/main/LocationTracker/app/src/main/res/layout/activity_view_details_location.xml): layout · Screen layout for the location detail view · `LocationTracker/app/src/main/res/layout/activity_view_details_location.xml`

## Connections

- Get Started → Sign In: entry · Starts the authentication flow
- Get Started → Sign Up: new user · Routes first-time users to account creation
- Sign Up → User DB: stores user · Persists new accounts locally
- Sign In → User DB: verifies user · Checks credentials against local users
- Sign In → Session State: sets login · Persists authenticated session state
- Sign Up → Session State: starts session · Marks the user as signed in after registration
- Session State → Main Activity: opens shell · Controls whether the authenticated app is shown
- Main Activity → Bottom Nav: hosts nav · Uses bottom navigation to switch primary fragments
- Bottom Nav → Home: tab · Main tracking dashboard tab
- Bottom Nav → History: tab · History browsing tab
- Bottom Nav → Profile: tab · Profile tab
- Home → Location Service: starts/stops · Controls background location capture
- Location Service → GPS Source: reads · Collects device GPS updates
- Location Service → Location DB: writes snapshot · Stores periodic location readings
- Location Service → Location Model: creates record · Materializes captured readings as model objects
- Location DB → History: feeds history · Provides stored records to the browsing screen
- History → Location Adapter: binds list · Displays records through a list adapter
- Location Adapter → Location Model: renders · Binds each saved location model into the list item UI
- History → Location Details: opens detail · Drills into a selected record
- Location Details → Details Layout: uses layout · Renders the per-record detail screen
- Home → Home Layout: uses layout · Renders the tracking dashboard UI
- History → History Layout: uses layout · Renders the history screen UI
- Main Activity → Profile: contains · Hosts the profile screen inside the authenticated shell