# leohsuprogramminglab/ntuef_survey_app architecture

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

- Interactive diagram: https://gitdiagram.com/leohsuprogramminglab/ntuef_survey_app
- Repository: https://github.com/leohsuprogramminglab/ntuef_survey_app

## Overview

##### Main components
a. Presentation Layer (UI & Navigation)
- Single Activity: MainActivity
- Router: NTUEFScreen enum → controls which Composable screen to display
- Composable Screens under `layout/` (e.g., SurveyScreen, PlotOptionsScreen, ResultDisplayScreen, DownloadUploadJsonScreen, SaveScreen)
- UI Widgets & Dialogs under `ui/widget/` and `ui/widget/dialog/`
- Theme definitions under `ui/theme/`
b. ViewModel Layer
- SurveyViewModel (in `viewModel/`) — holds UI state, exposes flows/Livedata
c. Domain/Data Layer
- DataSource (in `data/`): orchestrates calls to network and file I/O
- Models (in `model/`): e.g., PlotData, TreeData
- Utilities (in `utils/`): FileIO (JSON read/write), Permission handlers, general Func, ButtonHandlers
d. Network/API Layer
- Retrofit configuration in RetrofitInstance
- API definitions in DatabaseApi
- Data-transfer objects under `api/dataType/` grouped by endpoint (plotInfoResponse, plotsCatalogueResponse, surveyDataForUpload, uploadDataResponse, userAndConditionCodeResponse)
- Helpers in `api/Utils.kt`
e. Local Storage
- UI-package resources & mappings (survey.json, config.json in `ui-packages/`)
- Local JSON file generation via FileIO
f. External Services
- Remote database REST service (the endpoint targeted by DatabaseApi)

##### Relationships and data flows
- User interacts with UI Composables → UI events trigger SurveyViewModel methods
→ ViewModel invokes DataSource
→ DataSource either reads/writes local JSON via FileIO or calls DatabaseApi (Retrofit)
→ RetrofitInstance makes HTTP requests → remote DB → responses mapped to dataType objects
→ DataSource returns domain models or status back to ViewModel
→ ViewModel updates UI state → Composables re-compose to display results

##### Architectural patterns & design principles
- MVVM: clear separation between View (Compose UI), ViewModel, and Model/Data layers
- Single-Activity + Navigation by Router enum (NTUEFScreen)
- Dependency inversion: DataSource hides Retrofit details behind a simple interface
- Immutable data models for thread safety
- Compose theming for consistent styling

##### Detailed breakdown of components
- MainActivity
- hosts Compose NavHost
- Router (NTUEFScreen enum)
- defines route graph
- Screens (PlotOptionsScreen, SurveyScreen, etc.)
- UI→ViewModel calls like `viewModel.loadPlots()`
- SurveyViewModel
- methods: `downloadPlots()`, `saveSurvey()`, `uploadJson()`
- exposes StateFlows/LiveData to UI
- DataSource
- functions: `getPlotsCatalogue()`, `getPlotInfo()`, `prepareSurveyJson()`, `uploadSurveyJson()`
- DatabaseApi
- endpoints: `/catalogue`, `/plotInfo`, `/uploadSurvey`, `/userCodes`
- RetrofitInstance
- OkHttpClient, Interceptors, ConverterFactory
- FileIO
- read/write JSON to device storage
- Remote Database
- RESTful service, returns JSON

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% UI Layer
    subgraph "UI Layer"
        direction TB
        MainActivity["MainActivity"]:::ui
        Router["NTUEFScreen (Router)"]:::ui
        subgraph "Screens"
            direction TB
            SurveyScreen["SurveyScreen"]:::ui
            PlotOptionsScreen["PlotOptionsScreen"]:::ui
            ResultDisplayScreen["ResultDisplayScreen"]:::ui
            DownloadUploadJsonScreen["DownloadUploadJsonScreen"]:::ui
            SaveScreen["SaveScreen"]:::ui
        end
        subgraph "UI Widgets & Dialogs"
            direction TB
            UIWidgets["Widgets"]:::ui
            Dialogs["Dialogs"]:::ui
        end
        Theme["Theme Definitions"]:::ui
    end

    %% ViewModel Layer
    subgraph "ViewModel Layer"
        direction TB
        SurveyViewModel["SurveyViewModel"]:::vm
    end

    %% Data Layer
    subgraph "Data Layer"
        direction TB
        DataSource["DataSource"]:::data
        subgraph "Models"
            direction TB
            PlotData["PlotData"]:::data
            TreeData["TreeData"]:::data
        end
        subgraph "Utilities"
            direction TB
            FileIO["FileIO"]:::data
            Permission["Permission Handlers"]:::data
            Func["Func"]:::data
            ButtonHandlers["ButtonHandlers"]:::data
        end
    end

    %% Network/API Layer
    subgraph "Network/API Layer"
        direction TB
        RetrofitInstance["RetrofitInstance"]:::api
        DatabaseApi["DatabaseApi"]:::api
        UtilsAPI["API Utils"]:::api
        subgraph "DTOs"
            direction TB
            PlotInfoResp["plotInfoResponse"]:::api
            PlotsCatalogueResp["plotsCatalogueResponse"]:::api
            SurveyDataForUpload["surveyDataForUpload"]:::api
            UploadDataResp["uploadDataResponse"]:::api
            UserCondCodeResp["userAndConditionCodeResponse"]:::api
        end
    end

    %% Local Storage
    subgraph "Local Storage"
        direction TB
        Mappings["survey.json (Mappings)"]:::external
        BundledPackage["ui-packages/survey"]:::external
    end

    %% External Services
    RemoteDB["Remote Database"]:::external

    %% Connections
    MainActivity --> Router
    Router --> SurveyScreen
    Router --> PlotOptionsScreen
    Router --> ResultDisplayScreen
    Router --> DownloadUploadJsonScreen
    Router --> SaveScreen

    SurveyScreen -->|"user actions"| SurveyViewModel
    PlotOptionsScreen --> SurveyViewModel
    ResultDisplayScreen --> SurveyViewModel
    DownloadUploadJsonScreen --> SurveyViewModel
    SaveScreen --> SurveyViewModel

    SurveyViewModel -->|"coroutine calls"| DataSource

    DataSource --> FileIO
    DataSource --> DatabaseApi

    FileIO --> Mappings
    FileIO --> BundledPackage

    DatabaseApi --> RetrofitInstance
    RetrofitInstance --> RemoteDB
    RetrofitInstance --> UtilsAPI
    DatabaseApi --> PlotInfoResp
    DatabaseApi --> PlotsCatalogueResp
    DatabaseApi --> SurveyDataForUpload
    DatabaseApi --> UploadDataResp
    DatabaseApi --> UserCondCodeResp

    %% Click Events
    click MainActivity "https://github.com/leohsuprogramminglab/ntuef_survey_app/blob/main/app/src/main/java/com/example/ntufapp/MainActivity.kt"
    click Router "https://github.com/leohsuprogramminglab/ntuef_survey_app/blob/main/app/src/main/java/com/example/ntufapp/router/NTUEFScreen.kt"
    click SurveyScreen "https://github.com/leohsuprogramminglab/ntuef_survey_app/blob/main/app/src/main/java/com/example/ntufapp/layout/SurveyScreen.kt"
    click PlotOptionsScreen "https://github.com/leohsuprogramminglab/ntuef_survey_app/blob/main/app/src/main/java/com/example/ntufapp/layout/PlotOptionsScreen.kt"
    click ResultDisplayScreen "https://github.com/leohsuprogramminglab/ntuef_survey_app/blob/main/app/src/main/java/com/example/ntufapp/layout/ResultDisplayScreen.kt"
    click DownloadUploadJsonScreen "https://github.com/leohsuprogramminglab/ntuef_survey_app/blob/main/app/src/main/java/com/example/ntufapp/layout/DownloadUploadJsonScreen.kt"
    click SaveScreen "https://github.com/leohsuprogramminglab/ntuef_survey_app/blob/main/app/src/main/java/com/example/ntufapp/layout/SaveScreen.kt"
    click UIWidgets "https://github.com/leohsuprogramminglab/ntuef_survey_app/tree/main/app/src/main/java/com/example/ntufapp/ui/widget/"
    click Dialogs "https://github.com/leohsuprogramminglab/ntuef_survey_app/tree/main/app/src/main/java/com/example/ntufapp/ui/widget/dialog/"
    click Theme "https://github.com/leohsuprogramminglab/ntuef_survey_app/tree/main/app/src/main/java/com/example/ntufapp/ui/theme/"
    click SurveyViewModel "https://github.com/leohsuprogramminglab/ntuef_survey_app/blob/main/app/src/main/java/com/example/ntufapp/viewModel/SurveyViewModel.kt"
    click DataSource "https://github.com/leohsuprogramminglab/ntuef_survey_app/blob/main/app/src/main/java/com/example/ntufapp/data/DataSource.kt"
    click PlotData "https://github.com/leohsuprogramminglab/ntuef_survey_app/blob/main/app/src/main/java/com/example/ntufapp/model/PlotData.kt"
    click TreeData "https://github.com/leohsuprogramminglab/ntuef_survey_app/blob/main/app/src/main/java/com/example/ntufapp/model/TreeData.kt"
    click FileIO "https://github.com/leohsuprogramminglab/ntuef_survey_app/blob/main/app/src/main/java/com/example/ntufapp/utils/FileIO.kt"
    click Permission "https://github.com/leohsuprogramminglab/ntuef_survey_app/blob/main/app/src/main/java/com/example/ntufapp/utils/Permission.kt"
    click Func "https://github.com/leohsuprogramminglab/ntuef_survey_app/blob/main/app/src/main/java/com/example/ntufapp/utils/Func.kt"
    click ButtonHandlers "https://github.com/leohsuprogramminglab/ntuef_survey_app/blob/main/app/src/main/java/com/example/ntufapp/utils/ButtonHandlers.kt"
    click RetrofitInstance "https://github.com/leohsuprogramminglab/ntuef_survey_app/blob/main/app/src/main/java/com/example/ntufapp/api/RetrofitInstance.kt"
    click DatabaseApi "https://github.com/leohsuprogramminglab/ntuef_survey_app/blob/main/app/src/main/java/com/example/ntufapp/api/DatabaseApi.kt"
    click UtilsAPI "https://github.com/leohsuprogramminglab/ntuef_survey_app/blob/main/app/src/main/java/com/example/ntufapp/api/Utils.kt"
    click PlotInfoResp "https://github.com/leohsuprogramminglab/ntuef_survey_app/tree/main/app/src/main/java/com/example/ntufapp/api/dataType/plotInfoResponse/"
    click PlotsCatalogueResp "https://github.com/leohsuprogramminglab/ntuef_survey_app/tree/main/app/src/main/java/com/example/ntufapp/api/dataType/plotsCatalogueResponse/"
    click SurveyDataForUpload "https://github.com/leohsuprogramminglab/ntuef_survey_app/tree/main/app/src/main/java/com/example/ntufapp/api/dataType/surveyDataForUpload/"
    click UploadDataResp "https://github.com/leohsuprogramminglab/ntuef_survey_app/tree/main/app/src/main/java/com/example/ntufapp/api/dataType/uploadDataResponse/"
    click UserCondCodeResp "https://github.com/leohsuprogramminglab/ntuef_survey_app/tree/main/app/src/main/java/com/example/ntufapp/api/dataType/userAndConditionCodeResponse/"
    click Mappings "https://github.com/leohsuprogramminglab/ntuef_survey_app/blob/main/app/src/main/ui-package-resources/mappings/survey.json"
    click BundledPackage "https://github.com/leohsuprogramminglab/ntuef_survey_app/tree/main/app/src/main/ui-packages/survey/"

    %% Styles
    classDef ui fill:#cfe2f3,stroke:#2f75b5,color:#000
    classDef vm fill:#d9ead3,stroke:#6aa84f,color:#000
    classDef data fill:#f4cccc,stroke:#cc0000,color:#000
    classDef api fill:#ffe599,stroke:#bf9000,color:#000
    classDef external fill:#e7e6e6,stroke:#999999,color:#000
```
