# lahsineyounes/collecteterrain architecture

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

- Interactive diagram: https://gitdiagram.com/lahsineyounes/collecteterrain
- Repository: https://github.com/lahsineyounes/collecteterrain

## Overview

##### Project type and purpose
- This is a native Android mobile application (“CollecteTerrainApp”) targeting two user roles: field representatives and multi‐site managers.
- Purpose: allow field reps to collect geolocated data (photos, amounts, comments) and sync it in real time; allow managers to monitor teams on an embedded Google Map dashboard.

##### File structure
- Top‐level “app” module (Gradle Kotlin DSL) containing:
- src/main/java/com/example/collecteterrainapp
– Activities & Fragments divided by feature: auth (LoginFragment, RegisterFragment), shared (ProfileFragment), representative (AddCollecteFragment, CollecteFragment, etc.), manager (ManagerDashboardActivity, MapFragment, TeamStatsFragment, RepresentativeDetailFragment), plus MainActivity which hosts the Navigation component.
– adapter packages under both representative and manager.
– services (FirebaseService, LocationService)
– database helper (DatabaseHelper for SQLite local storage)
– models (Collection, Site, User)
– utils (AuthUtils, SessionManager, DateUtils)
- Navigation graphs in res/navigation
- Resource hierarchies for layouts, drawables, menus
- Build & deployment files: Gradle wrapper, build.gradle.kts, proguard, Google services JSON (Firebase), backup/data extraction XMLs.
- Tests: instrumented tests under androidTest, unit tests under test.

##### README for insights
- Real‐time sync via Firebase (or fallback to SQLite).
- Google Maps integration for live tracking.
- Roles: Rep vs Manager, each with tailored dashboard.
- Mentions optional web-scraping with Jsoup (extensibility point but not core).

##### Main components & interactions (to include
A. Mobile App (Android APK)
1. UI Layer
- Activities & Fragments
- Login/Register
- Representative dashboard & collection forms
- Manager dashboard & map view / team stats
- Navigation Component (mobile_navigation.xml, manager_navigation.xml)
2. Service Layer
- AuthUtils & SessionManager (manages tokens/user sessions)
- LocationService (foreground service providing GPS updates)
- FirebaseService (wraps Firebase SDK calls: Realtime Database, Authentication, Cloud Storage for photos)
3. Data Layer
- SQLite via DatabaseHelper (local cache, offline mode)
- Data models (Collection, Site, User)
4. External Libraries
- Google Maps SDK
- Firebase SDK (Auth, Realtime Database, Cloud Storage)
- Jsoup (optional web-scraping extension)

B. Remote Backend & Cloud Services
- Firebase Authentication
- Firebase Realtime Database
- Firebase Cloud Storage
- (Optional) External Web Scraping Targets when implemented

C. External Dependencies
- Google Maps Platform (Map tiles, routing)
- Internet / mobile network

##### Relationships & data flow
- User interacts with UI → UI calls Service Layer
- Service Layer
- AuthUtils invokes Firebase Auth for login/register
- LocationService pushes GPS updates to UI & optionally to Firebase
- FirebaseService reads/writes models to Realtime Database & Cloud Storage
- Data Layer
- DatabaseHelper persists data locally for offline access
- Sync logic reconciles local SQLite with Firebase when network available
- Manager App Screens subscribe to Firebase real‐time updates to plot representative positions on the map
- Optional web-scraping module can fetch external data, feed into local DB or directly into Firebase via a background job

##### Architectural patterns & design principles
- Layered architecture: UI → Service → Data
- Single Responsibility: separate packages for auth, manager, representative, shared
- Offline-first with local SQLite caching and sync service
- Real-time communication via Firebase pub/sub model
- Android Navigation Graph for decoupled screen flows

##### Final focus
- Be comprehensive: capture every major package and service
- Both horizontal layering (UI → Services → Data) and vertical feature slices (Auth, Representative, Manager)
- Real-time sync and offline-cache paths are clearly differentiated

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% UI Layer
    subgraph "UI Layer" 
        style UI fill:#CCE5FF,stroke:#3399FF
        Login["LoginFragment"]:::ui
        Register["RegisterFragment"]:::ui
        Profile["ProfileFragment"]:::ui
        RepDash["RepresentantDashboardActivity"]:::ui
        AddCollecte["AddCollecteFragment"]:::ui
        CollecteList["CollecteFragment"]:::ui
        CollecteDetail["CollecteDetailFragment"]:::ui
        ManDash["ManagerDashboardActivity"]:::ui
        MapView["MapFragment"]:::ui
        TeamStats["TeamStatsFragment"]:::ui
        RepDetail["RepresentativeDetailFragment"]:::ui
        MainAct["MainActivity"]:::ui
        MobileNav["mobile_navigation.xml"]:::ui
        ManagerNav["manager_navigation.xml"]:::ui
    end

    %% Service Layer
    subgraph "Service Layer"
        style Service fill:#E6FFCC,stroke:#33CC33
        AuthUtils["AuthUtils"]:::service
        SessionMgr["SessionManager"]:::service
        LocationSvc["LocationService"]:::service
        FirebaseSvc["FirebaseService"]:::service
    end

    %% Data Layer
    subgraph "Data Layer"
        style Data fill:#FFF0CC,stroke:#FF9933
        DBHelper["DatabaseHelper"]:::data
        CollectionModel["Collection"]:::data
        SiteModel["Site"]:::data
        UserModel["User"]:::data
    end

    %% External Cloud Services
    subgraph "Firebase Cloud" 
        style Cloud fill:#F0E6FF,stroke:#9933FF
        FBAuth["Firebase Authentication"]:::cloud
        FBDB["Realtime Database"]:::cloud
        FBStorage["Cloud Storage"]:::cloud
    end

    %% External Libraries & APIs
    subgraph "External Dependencies"
        style Ext fill:#ECECEC,stroke:#888888
        GoogleMapsSDK["Google Maps SDK"]:::external
        Jsoup["Jsoup"]:::external
        Internet["Internet / Mobile Network"]:::external
        MapsAPI["Google Maps Platform"]:::external
    end

    %% Relationships
    Login -->|calls| AuthUtils
    Register -->|calls| AuthUtils
    Profile -->|uses session| SessionMgr
    MainAct -->|hosts| MobileNav
    MainAct -->|hosts| ManagerNav
    RepDash -->|navigates via| MobileNav
    AddCollecte -->|navigates via| MobileNav
    CollecteList -->|navigates via| MobileNav
    CollecteDetail -->|navigates via| MobileNav
    ManDash -->|navigates via| ManagerNav
    MapView -->|navigates via| ManagerNav
    TeamStats -->|navigates via| ManagerNav
    RepDetail -->|navigates via| ManagerNav

    %% UI to Service
    Login -->|Firebase SDK| FirebaseSvc
    Register -->|Firebase SDK| FirebaseSvc
    AuthUtils -->|Auth API| FBAuth
    SessionMgr -->|stores| UserModel
    LocationSvc -->|provides GPS| RepDash
    LocationSvc -->|pushes updates| FirebaseSvc
    FirebaseSvc -->|reads/writes| FBDB
    FirebaseSvc -->|uploads photos| FBStorage

    %% Service to Data
    FirebaseSvc -->|sync| DBHelper
    DBHelper -->|persist| CollectionModel
    DBHelper -->|persist| SiteModel
    DBHelper -->|persist| UserModel

    %% Data sync
    DBHelper -->|sync when online| FBDB
    FBDB -->|real-time updates| FBDB
    FBDB -->|pushes positions| MapView

    %% External Libraries & APIs usage
    MapView -->|REST| MapsAPI
    GoogleMapsSDK -->|renders| MapView
    Jsoup -->|HTTP| DBHelper

    %% Click Events
    click Login "https://github.com/lahsineyounes/collecteterrain/blob/master/app/src/main/java/com/example/collecteterrainapp/auth/LoginFragment.java"
    click Register "https://github.com/lahsineyounes/collecteterrain/blob/master/app/src/main/java/com/example/collecteterrainapp/auth/RegisterFragment.java"
    click Profile "https://github.com/lahsineyounes/collecteterrain/blob/master/app/src/main/java/com/example/collecteterrainapp/shared/ProfileFragment.java"
    click RepDash "https://github.com/lahsineyounes/collecteterrain/blob/master/app/src/main/java/com/example/collecteterrainapp/representative/RepresentantDashboardActivity.java"
    click AddCollecte "https://github.com/lahsineyounes/collecteterrain/blob/master/app/src/main/java/com/example/collecteterrainapp/representative/AddCollecteFragment.java"
    click CollecteList "https://github.com/lahsineyounes/collecteterrain/blob/master/app/src/main/java/com/example/collecteterrainapp/representative/CollecteFragment.java"
    click CollecteDetail "https://github.com/lahsineyounes/collecteterrain/blob/master/app/src/main/java/com/example/collecteterrainapp/representative/CollecteDetailFragment.java"
    click ManDash "https://github.com/lahsineyounes/collecteterrain/blob/master/app/src/main/java/com/example/collecteterrainapp/manager/ManagerDashboardActivity.java"
    click MapView "https://github.com/lahsineyounes/collecteterrain/blob/master/app/src/main/java/com/example/collecteterrainapp/manager/MapFragment.java"
    click TeamStats "https://github.com/lahsineyounes/collecteterrain/blob/master/app/src/main/java/com/example/collecteterrainapp/manager/TeamStatsFragment.java"
    click RepDetail "https://github.com/lahsineyounes/collecteterrain/blob/master/app/src/main/java/com/example/collecteterrainapp/manager/RepresentativeDetailFragment.java"
    click MobileNav "https://github.com/lahsineyounes/collecteterrain/blob/master/app/src/main/res/navigation/mobile_navigation.xml"
    click ManagerNav "https://github.com/lahsineyounes/collecteterrain/blob/master/app/src/main/res/navigation/manager_navigation.xml"
    click AuthUtils "https://github.com/lahsineyounes/collecteterrain/blob/master/app/src/main/java/com/example/collecteterrainapp/utils/AuthUtils.java"
    click SessionMgr "https://github.com/lahsineyounes/collecteterrain/blob/master/app/src/main/java/com/example/collecteterrainapp/utils/SessionManager.java"
    click LocationSvc "https://github.com/lahsineyounes/collecteterrain/blob/master/app/src/main/java/com/example/collecteterrainapp/services/LocationService.java"
    click FirebaseSvc "https://github.com/lahsineyounes/collecteterrain/blob/master/app/src/main/java/com/example/collecteterrainapp/services/FirebaseService.java"
    click DBHelper "https://github.com/lahsineyounes/collecteterrain/blob/master/app/src/main/java/com/example/collecteterrainapp/database/DatabaseHelper.java"
    click CollectionModel "https://github.com/lahsineyounes/collecteterrain/blob/master/app/src/main/java/com/example/collecteterrainapp/shared/models/Collection.java"
    click SiteModel "https://github.com/lahsineyounes/collecteterrain/blob/master/app/src/main/java/com/example/collecteterrainapp/shared/models/Site.java"
    click UserModel "https://github.com/lahsineyounes/collecteterrain/blob/master/app/src/main/java/com/example/collecteterrainapp/shared/models/User.java"
    click MainAct "https://github.com/lahsineyounes/collecteterrain/blob/master/app/src/main/java/com/example/collecteterrainapp/MainActivity.java"

    %% Styles
    classDef ui fill:#CCE5FF,stroke:#3399FF,font-weight:bold
    classDef service fill:#E6FFCC,stroke:#33CC33,font-weight:bold
    classDef data fill:#FFF0CC,stroke:#FF9933,font-weight:bold
    classDef cloud fill:#F0E6FF,stroke:#9933FF,font-weight:bold
    classDef external fill:#ECECEC,stroke:#888888,font-weight:bold
```
