# albrivas/gasguru architecture

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

- Interactive diagram: https://gitdiagram.com/albrivas/gasguru
- Repository: https://github.com/albrivas/gasguru

## Overview

##### Main Components
- App Module – This is the entry point of the Android application containing the Application class, MainActivity, and other core UI elements.
- Core Modules – These include multiple sub-components:
- Core/Common: Shared utilities and common functionalities (e.g., Coroutine Dispatchers, common utilities).
- Core/Data: Contains repository implementations, network mappers, and data sources that abstract interaction with remote APIs and other sources.
- Core/Domain: Implements use cases (business logic) and encapsulates the rules and processes of the application (e.g., fuel station queries, location handling, connectivity).
- Core/Database: Handles interactions with the local database schemas, DAOs, and migration logic.
- Core/Model: Defines data models used across the layers (e.g., FuelStation, UserData, Filters).
- Core/Network: Manages network operations, API service definitions, remote data sources, and network models.
- Core/UI and Core/UIKit: Provide theming, reusable UI components (buttons, chips, navigation bars, markers, etc.), and common visual elements.
- Core/Testing: Contains test rules and base test setups for unit and instrumented testing.
- Feature Modules – These modules focus on specific functionalities of the app, such as:
- Detail Station
- Favorite List Station
- Onboarding
- Profile
- Station Map
Each of these is structured in a similar way, containing presentation (UI), navigation, and sometimes domain-specific logic.

##### Relationships and Interactions
- The App Module initializes and ties together the entire application. It sets up the navigation host and directs the user flow to the appropriate feature module.
- The UI layer (including feature modules and Core/UI/Core/UIKit) interacts with ViewModels which then communicate with the Domain layer (use cases).
- Use Cases in the Domain layer invoke Repository interfaces defined in Core/Data.
- The Data layer abstracts access to two major external data sources:
- Network: The network module (using Retrofit API services and data sources) fetches real-time fuel price information.
- Local Database: The database module (using DAOs and migration scripts) caches or persists data for offline use.
- Common modules facilitate shared logic, while testing modules are used to validate each layer independently.

##### Architectural Patterns and Design Principles
- Clean Architecture – Clear separation of concerns across UI (presentation), Domain (business logic), and Data (infrastructure).
- MVVM Pattern – The project shows ViewModel classes for each UI screen, which handle state and logic.
- Modularization – The project is structured into separate modules (app, core, feature) to improve maintainability, testability, and independent evolution of features.
- Dependency Injection – Although not explicitly stated, the presence of DI modules (for example in data and network) suggests a DI framework (potentially Hilt/Dagger).

##### Relevant Technologies & Frameworks
- Android (Kotlin-based) – The core application and feature modules are built using Kotlin.
- Gradle (Kotlin DSL) – The build configuration is managed via Gradle with Kotlin DSL.
- Navigation Components – Used for routing and navigation across screens.
- Retrofit (or similar) in the Network module – For API communication.
- Room (or equivalent) in the Database module – For local data persistence.
- Testing Frameworks – Instrumented tests (Android tests) and unit tests are organized in the testing modules.
- UI Components – Custom UI elements in the Core/UIKit module for a consistent app look and feel.

##### Detail and Clarity
- The goal is to capture each essential architectural element: from the Android-specific entry point in the App module to the multiple feature-driven and shared modules.
- This design is particularly suited for a full-stack mobile (Android) application where separation of concerns, modularization, and clear data flow are essential.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Presentation Layer (UI)
    subgraph "Presentation Layer (UI)"
        A["App Module (Entry Point)"]:::ui
        DM["Feature Module – Detail Station"]:::ui
        FM["Feature Module – Favorite List Station"]:::ui
        OM["Feature Module – Onboarding"]:::ui
        PM["Feature Module – Profile"]:::ui
        SM["Feature Module – Station Map"]:::ui
        UIC["Core/UI (Theming & Reusable UI)"]:::ui
        UIT["Core/UIKit (Custom UI Components)"]:::ui
    end

    %% Domain Layer
    subgraph "Domain Layer"
        D["Core/Domain (Use Cases)"]:::domain
    end

    %% Data Layer
    subgraph "Data Layer"
        DT["Core/Data (Repositories & Mappers)"]:::data
        N["Core/Network (API Services)"]:::data
        DB["Core/Database (Local Database)"]:::data
    end

    %% Support Layer
    subgraph "Support Layer"
        C["Core/Common (Shared Utilities)"]:::support
        M["Core/Model (Data Models)"]:::support
        T["Core/Testing (Test Suites)"]:::support
    end

    %% Connections within Presentation Layer
    A -->|"initializes"| DM
    A -->|"initializes"| FM
    A -->|"initializes"| OM
    A -->|"initializes"| PM
    A -->|"initializes"| SM
    A -->|"uses"| UIC
    A -->|"uses"| UIT

    %% UI Feature Modules interact with Domain Layer (via ViewModels)
    DM -->|"triggers"| D
    FM -->|"triggers"| D
    OM -->|"triggers"| D
    PM -->|"triggers"| D
    SM -->|"triggers"| D

    %% Domain Layer uses Data Layer
    D -->|"invokes"| DT

    %% Data Layer interactions
    DT -->|"fetches from"| N
    DT -->|"fetches from"| DB

    %% Dotted dependencies for shared support
    D -.->|"depends_on"| C
    D -.->|"depends_on"| M
    DT -.->|"uses"| C
    DT -.->|"uses"| M
    UIC -.->|"leverages"| C
    UIT -.->|"leverages"| C

    %% Testing support (dotted lines indicating testing coverage)
    T -.->|"tests"| A
    T -.->|"tests"| D
    T -.->|"tests"| DT

    %% Styling classes
    classDef ui fill:#AEDFF7,stroke:#333,stroke-width:2px;
    classDef domain fill:#C3E6CB,stroke:#333,stroke-width:2px;
    classDef data fill:#F7C6C7,stroke:#333,stroke-width:2px;
    classDef support fill:#F9E79F,stroke:#333,stroke-width:2px;

    %% Click Events
    click A "https://github.com/albrivas/gasguru/tree/main/app/src/main/java/com/gasguru"
    click UIC "https://github.com/albrivas/gasguru/tree/main/core/ui"
    click UIT "https://github.com/albrivas/gasguru/tree/main/core/uikit"
    click D "https://github.com/albrivas/gasguru/tree/main/core/domain"
    click DT "https://github.com/albrivas/gasguru/tree/main/core/data"
    click N "https://github.com/albrivas/gasguru/tree/main/core/network"
    click DB "https://github.com/albrivas/gasguru/tree/main/core/database"
    click C "https://github.com/albrivas/gasguru/tree/main/core/common"
    click M "https://github.com/albrivas/gasguru/tree/main/core/model"
    click T "https://github.com/albrivas/gasguru/tree/main/core/testing"
    click DM "https://github.com/albrivas/gasguru/tree/main/feature/detail-station"
    click FM "https://github.com/albrivas/gasguru/tree/main/feature/favorite-list-station"
    click OM "https://github.com/albrivas/gasguru/tree/main/feature/onboarding"
    click PM "https://github.com/albrivas/gasguru/tree/main/feature/profile"
    click SM "https://github.com/albrivas/gasguru/tree/main/feature/station-map"
```
