# tbiyiktas/android-location architecture

> Architecture diagram of the GitHub repository tbiyiktas/android-location, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-08-18). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/tbiyiktas/android-location
- Repository: https://github.com/tbiyiktas/android-location

## Overview

##### Project Type and Purpose
- This is an Android mobile app (“Android-Location”) whose purpose is to subscribe to, capture, and display device location history.
- It bundles a custom location library under app/src/main/java/lib/location that abstracts and manages location retrieval, backpressure, caching, and command execution.

##### File Structure
Top-level:
- build scripts (build.gradle.kts, settings.gradle.kts, gradle wrapper)
- app/ – the Android application module
Within app/:
– src/main/java/com/example/androidlocation: UI layer (LocationActivity, LocationHistoryAdapter) and MyApplication
– src/main/java/lib/location: location-service library
· core interfaces: ILocationCenter, ILocationClient, LocationCallback, LocationData, etc.
· adapters: FusedLocationClientAdapter (wraps Google Play Services)
· config: LocationConfigProvider, StaticLocationConfigProvider
· storage: LocationHistoryStore
· commands: StartUpdates, StopUpdates, GetLatestValid, etc.
· runtime: LocationDispatcher, Cancellables
Resources: layouts, drawables, XML rules
Tests: androidTest and unit test packages

##### Extract Architectural Insights from README
- Naming conventions in lib/location suggest a layered service with a command pattern and backpressure handling.

##### Main Components & Boundaries
a. Presentation Layer (UI)
- LocationActivity: entry point; binds to LocationCenter, displays history via LocationHistoryAdapter.
b. Application Layer
- MyApplication: application subclass, initializes LocationCenter.
c. Domain/Service Layer (lib/location)
- ILocationCenter (Facade): primary API for clients to start/stop updates, query history.
- LocationCenter (Implementation): orchestrates clients, dispatches commands.
- LocationCommands: encapsulate operations (StartUpdates, StopUpdates, GetLatestValid)
- LocationDispatcher: internal event loop for distributing data or errors.
- BackpressurePolicy, Cancellable: runtime control.
d. Data Layer
- FusedLocationClientAdapter: adapter to Google Play Services fused location provider (external dependency).
- LocationHistoryStore: local store of past LocationData (in-memory or persisted).
e. External & System Services
- Google Play Services FusedLocationProvider (external API)
- Android framework LocationManager (implicitly via adapter)
- Local file/db (if implemented in LocationHistoryStore)

##### Relationships & Data Flow
1) User opens UI → LocationActivity requests LocationCenter.startUpdates()
2) LocationCenter issues StartUpdatesCommand → injected to FusedLocationClientAdapter
3) FusedLocationClientAdapter registers with Google Play Services
4) As GPS/Wi-Fi fixes come in → LocationCallback → LocationDispatcher
5) Dispatcher applies BackpressurePolicy → emits LocationData →
- persists to LocationHistoryStore
- notifies subscribed UI listeners (via callback interface)
6) LocationActivity receives updates → updates RecyclerView via LocationHistoryAdapter
7) User stops updates → LocationCenter.stopUpdates() → StopUpdatesCommand

##### Architectural Patterns & Principles
- Layered architecture (Presentation → Application → Domain/Service → Data → External).
- Command pattern (Start, Stop, GetLatest).
- Adapter pattern (FusedLocationClientAdapter to bridge external service).
- Observer/Callback (LocationUpdateListener).
- Single Responsibility & Dependency Inversion (ILocationClient, ILocationCenter).

- Component names: LocationActivity, LocationCenter, ILocationClient, FusedLocationClientAdapter, LocationDispatcher, LocationHistoryStore, etc.
- Interfaces and patterns: ILocationCenter, LocationCommand, BackpressurePolicy.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Presentation Layer"
        LA["LocationActivity"]:::presentation
        LHA["LocationHistoryAdapter"]:::presentation
    end

    subgraph "Application Layer"
        APP["MyApplication"]:::application
    end

    subgraph "Domain/Service Layer"
        ILC["ILocationCenter"]:::domain
        LC["LocationCenter"]:::domain
        ILCli["ILocationClient"]:::domain
        LCBK["LocationCallback"]:::domain
        LDAT["LocationData"]:::domain
        BPP["BackpressurePolicy"]:::domain
        CBL["Cancellable"]:::domain
        LUL["LocationUpdateListener"]:::domain
        LCP["LocationConfigProvider"]:::domain
        SLP["StaticLocationConfigProvider"]:::domain

        subgraph "Commands"
            LCMD["LocationCommand"]:::domain
            SUC["StartUpdatesCommand"]:::domain
            STC["StopUpdatesCommand"]:::domain
            GLC["GetLatestValidCommand"]:::domain
            LCDF["LocationCommands"]:::domain
        end

        subgraph "Runtime"
            LDSP["LocationDispatcher"]:::domain
            CBLM["Cancellables"]:::domain
        end
    end

    subgraph "Data Layer"
        FLA["FusedLocationClientAdapter"]:::data
        LHS["LocationHistoryStore"]:::data
    end

    subgraph "External Services"
        GPS["Google Play Services\nFusedLocationProvider"]:::external
        AFM["Android Framework\nLocationManager"]:::external
        LocalDB["Local File/DB"]:::external
    end

    %% Relationships
    LA -->|"startUpdates()"| ILC
    LA -->|"registerListener()"| ILC
    APP -->|"init ILocationCenter()"| LC
    ILC -->|"implemented by"| LC
    LC -->|"uses"| ILCli
    LC -->|"configure via"| LCP
    SLP -->|"provides config"| LC
    LC -->|"issue"| SUC
    LC -->|"issue"| STC
    LC -->|"issue"| GLC
    SUC -->|"executes on"| FLA
    STC -->|"executes on"| FLA
    GLC -->|"executes on"| FLA
    FLA -->|"registers with"| GPS
    FLA -->|"registers with"| AFM
    GPS -->|"onLocationResult()"| LCBK
    AFM -->|"onLocationResult()"| LCBK
    LCBK -->|"dispatch()"| LDSP
    LDSP -->|"apply policy"| BPP
    LDSP -->|"emit data"| LDAT
    LDSP -->|"persist"| LHS
    LDSP -->|"notify"| LUL
    LUL -->|"onUpdate()"| LA
    LHS -->|"store data"| LocalDB

    %% Click Events
    click LA "https://github.com/tbiyiktas/android-location/blob/main/app/src/main/java/com/example/androidlocation/LocationActivity.java"
    click LHA "https://github.com/tbiyiktas/android-location/blob/main/app/src/main/java/com/example/androidlocation/LocationHistoryAdapter.java"
    click APP "https://github.com/tbiyiktas/android-location/blob/main/app/src/main/java/com/example/androidlocation/MyApplication.java"
    click ILC "https://github.com/tbiyiktas/android-location/blob/main/app/src/main/java/lib/location/ILocationCenter.java"
    click LC "https://github.com/tbiyiktas/android-location/blob/main/app/src/main/java/lib/location/LocationCenter.java"
    click ILCli "https://github.com/tbiyiktas/android-location/blob/main/app/src/main/java/lib/location/ILocationClient.java"
    click LCBK "https://github.com/tbiyiktas/android-location/blob/main/app/src/main/java/lib/location/LocationCallback.java"
    click LDAT "https://github.com/tbiyiktas/android-location/blob/main/app/src/main/java/lib/location/LocationData.java"
    click BPP "https://github.com/tbiyiktas/android-location/blob/main/app/src/main/java/lib/location/BackpressurePolicy.java"
    click CBL "https://github.com/tbiyiktas/android-location/blob/main/app/src/main/java/lib/location/Cancellable.java"
    click LUL "https://github.com/tbiyiktas/android-location/blob/main/app/src/main/java/lib/location/LocationUpdateListener.java"
    click LCP "https://github.com/tbiyiktas/android-location/blob/main/app/src/main/java/lib/location/LocationConfigProvider.java"
    click SLP "https://github.com/tbiyiktas/android-location/blob/main/app/src/main/java/lib/location/StaticLocationConfigProvider.java"
    click LCMD "https://github.com/tbiyiktas/android-location/blob/main/app/src/main/java/lib/location/commands/LocationCommand.java"
    click SUC "https://github.com/tbiyiktas/android-location/blob/main/app/src/main/java/lib/location/commands/StartUpdatesCommand.java"
    click STC "https://github.com/tbiyiktas/android-location/blob/main/app/src/main/java/lib/location/commands/StopUpdatesCommand.java"
    click GLC "https://github.com/tbiyiktas/android-location/blob/main/app/src/main/java/lib/location/commands/GetLatestValidCommand.java"
    click LCDF "https://github.com/tbiyiktas/android-location/blob/main/app/src/main/java/lib/location/commands/LocationCommands.java"
    click LDSP "https://github.com/tbiyiktas/android-location/blob/main/app/src/main/java/lib/location/runtime/LocationDispatcher.java"
    click CBLM "https://github.com/tbiyiktas/android-location/blob/main/app/src/main/java/lib/location/runtime/Cancellables.java"
    click FLA "https://github.com/tbiyiktas/android-location/blob/main/app/src/main/java/lib/location/FusedLocationClientAdapter.java"
    click LHS "https://github.com/tbiyiktas/android-location/blob/main/app/src/main/java/lib/location/LocationHistoryStore.java"

    %% Styles
    classDef presentation fill:#bbdefb,stroke:#1e88e5,color:#0d47a1;
    classDef application fill:#e1bee7,stroke:#8e24aa,color:#4a148c;
    classDef domain fill:#c8e6c9,stroke:#43a047,color:#1b5e20;
    classDef data fill:#ffe0b2,stroke:#fb8c00,color:#e65100;
    classDef external fill:#eeeeee,stroke:#9e9e9e,color:#424242;
```
