# k3ssdev/stacompanion architecture

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

- Interactive diagram: https://gitdiagram.com/k3ssdev/stacompanion
- Repository: https://github.com/k3ssdev/stacompanion

## Overview

##### Project Type & Purpose
- The project is an Android mobile companion app built in Java/Kotlin using Android Studio. Its purpose is to help players manage character and starship sheets, perform specialized dice rolls, and export PDFs of game sheets for the Star Trek Adventures RPG.
- Key indicators include references in the README to handling offline data with an SQLite database, UI components such as Activities and Fragments, AdMob integration for monetization, and utilities for PDF generation.

##### File Structure
- The top-level “app” directory is the main module. The structure splits into sources (app/src/main, app/src/test, and app/src/androidTest), resources (app/src/main/res for layouts, drawables, animations, etc.), and assets (PDF files and fonts).
- There are build files (build.gradle.kts, settings.gradle.kts) and CI configuration under .github/workflows, which suggest automated builds and testing.

##### Key Components
a. User Interface Layer:
- Activities (e.g., MainActivity, LoginActivity, SplashActivity, CharacterSheetEditActivity, LegalActivity).
- Fragments (e.g., CharactersFragment, DiceFragment, SettingsFragment, CharacterSheetFragment, along with its supporting fragments like DataTabFragment, SkillsFragment, etc.).
- ViewModels (e.g., CharacterSheetViewModel, DiceViewModel, SettingsViewModel) which mediate between the UI and the data.
- Adapters and custom UI components (e.g., CharacterFragmentAdapter, DiceResultAdapter, SpaceItemDecoration).

b. Data Management Layer:
- Data models and helpers in the data package (e.g., CharacterSheet, SheetSettings, Starship, CharacterDbHelper).
- SQLite database is the key data storage mechanism, replacing Firebase authentication/data storage as noted in the README.

c. Utility & External Integration Layer:
- PDF Generation (e.g., PdfUtil) for exporting sheets.
- Assets used for dice (XML files for dice faces and animations for rolling) and fonts.
- AdMob integration (for displaying ads after the splash screen) which should be visually represented as an external service.
- Legacy integration with Firebase (detailed in the README) is marked for replacement, but may be represented as a legacy component.

d. Build and CI/CD Components:
- CI configuration via .github/workflows (android_ci.yml) and Gradle build scripts.
- Documentation components (README, sta_tree.md).

##### Relationships and Interactions
- UI components (Activities/Fragments) interact with their corresponding ViewModels.
- ViewModels communicate with the Data Layer (via CharacterDbHelper and other data sources).
- User actions (e.g., initiating a dice roll or editing a character sheet) flow from UI to the Data Layer with adapters and utility services (like PdfUtil for exporting).
- External integrations, such as AdMob, should be depicted connected to the UI (typically invoked after the splash screen) and the build pipeline components (Gradle, CI).

##### Architectural Patterns & Design Principles
- The project applies a modular, layered design that aligns well with MVVM (Model-View-ViewModel), where:
- The View layer (Activities/Fragments) handles user interactions.
- ViewModels serve as an abstraction between the UI and the data management.
- The data layer (SQLite database, data models, helper classes) encapsulates business logic and storage.
- Separation of concerns, reusability (via modular packages) and abstraction (UI components being independent from the back-end data management).

## Diagram (Mermaid)

```mermaid
graph TD
    %% UI Layer
    subgraph "UI Layer"
        direction TB
        MActivity["MainActivity"]:::ui
        LActivity["LoginActivity"]:::ui
        SActivity["SplashActivity"]:::ui
        LglActivity["LegalActivity"]:::ui
        CSActivity["CharacterSheetEditActivity"]:::ui
        ChFragment["CharactersFragment"]:::ui
        CSFragment["CharacterSheetFragment"]:::ui
        DTFragment["DataTabFragment"]:::ui
        SkFragment["SkillsFragment"]:::ui
        OtFragment["OthersFragment"]:::ui
        StFragment["StatusFragment"]:::ui
        DFragment["DiceFragment"]:::ui
        SettFragment["SettingsFragment"]:::ui
        CFAdapter["CharacterFragmentAdapter"]:::ui
        DRAdapter["DiceResultAdapter"]:::ui
        SpaceDec["SpaceItemDecoration"]:::ui
    end

    %% Presentation / Logic Layer (ViewModels)
    subgraph "Presentation / Logic Layer (ViewModels)"
        direction TB
        CSVM["CharacterSheetViewModel"]:::presentation
        DVM["DiceViewModel"]:::presentation
        SVML["SettingsViewModel"]:::presentation
    end

    %% Data Management Layer
    subgraph "Data Management Layer"
        direction TB
        CharSheet["CharacterSheet"]:::data
        SheetSet["SheetSettings"]:::data
        Starship["Starship"]:::data
        DbHelper["CharacterDbHelper"]:::data
    end

    %% Utility & External Integration Layer
    subgraph "Utility & External Integration Layer"
        direction TB
        PdfUtilU["PdfUtil"]:::utility
        AdsService["STACompanionAds"]:::utility
        PDFAsset["STA_personaje.pdf"]:::utility
    end

    %% Build and CI/CD Tools
    subgraph "Build and CI/CD Tools"
        direction TB
        CIConf["android_ci.yml"]:::build
        GradleApp["app/build.gradle.kts"]:::build
        GradleRoot["build.gradle.kts"]:::build
        DocRead["README.MD"]:::build
        DocSta["sta_tree.md"]:::build
    end

    %% UI Layer to Presentation/Logic Layer Connections
    MActivity -->|"triggers"| CSVM
    CSActivity -->|"editsData"| CSVM
    ChFragment -->|"displaysData"| CSVM
    CSFragment -->|"showsDetails"| CSVM
    DTFragment -->|"switchesView"| CSVM
    SkFragment -->|"showsSkills"| CSVM
    OtFragment -->|"showsOthers"| CSVM
    StFragment -->|"showsStatus"| CSVM
    DFragment -->|"rollsDice"| DVM
    SettFragment -->|"updatesSettings"| SVML

    %% UI Adapters Associations
    ChFragment -->|"usesAdapter"| CFAdapter
    DFragment -->|"usesAdapter"| DRAdapter
    DFragment -->|"usesDecoration"| SpaceDec

    %% Presentation/Logic to Data Management Connections
    CSVM -->|"fetchesSaves"| DbHelper
    DVM -->|"accesses"| DbHelper
    SVML -->|"updates"| DbHelper
    CSVM -->|"manages"| CharSheet
    CSVM -->|"manages"| SheetSet
    CSVM -->|"manages"| Starship

    %% UI Interactions with Utility & External Integration Layer
    CSActivity -->|"exportsPDF"| PdfUtilU
    SActivity -->|"loadsAds"| AdsService

    %% Build and CI/CD Connections
    GradleApp -->|"builds"| CIConf
    GradleRoot -->|"builds"| CIConf
    CIConf -->|"documents"| DocRead
    CIConf -->|"documents"| DocSta

    %% Click Events
    click MActivity "https://github.com/k3ssdev/stacompanion/blob/master/app/src/main/java/io/github/k3ssdev/stacompanion/MainActivity.java"
    click LActivity "https://github.com/k3ssdev/stacompanion/blob/master/app/src/main/java/io/github/k3ssdev/stacompanion/LoginActivity.java"
    click SActivity "https://github.com/k3ssdev/stacompanion/blob/master/app/src/main/java/io/github/k3ssdev/stacompanion/SplashActivity.java"
    click LglActivity "https://github.com/k3ssdev/stacompanion/blob/master/app/src/main/java/io/github/k3ssdev/stacompanion/LegalActivity.java"
    click CSActivity "https://github.com/k3ssdev/stacompanion/blob/master/app/src/main/java/io/github/k3ssdev/stacompanion/ui/characters/CharacterSheetEditActivity.java"
    click ChFragment "https://github.com/k3ssdev/stacompanion/blob/master/app/src/main/java/io/github/k3ssdev/stacompanion/ui/characters/CharactersFragment.java"
    click CSFragment "https://github.com/k3ssdev/stacompanion/blob/master/app/src/main/java/io/github/k3ssdev/stacompanion/ui/characters/charactersheet/CharacterSheetFragment.java"
    click DTFragment "https://github.com/k3ssdev/stacompanion/blob/master/app/src/main/java/io/github/k3ssdev/stacompanion/ui/characters/charactersheet/DataTabFragment.java"
    click SkFragment "https://github.com/k3ssdev/stacompanion/blob/master/app/src/main/java/io/github/k3ssdev/stacompanion/ui/characters/charactersheet/SkillsFragment.java"
    click OtFragment "https://github.com/k3ssdev/stacompanion/blob/master/app/src/main/java/io/github/k3ssdev/stacompanion/ui/characters/charactersheet/OthersFragment.java"
    click StFragment "https://github.com/k3ssdev/stacompanion/blob/master/app/src/main/java/io/github/k3ssdev/stacompanion/ui/characters/charactersheet/StatusFragment.java"
    click DFragment "https://github.com/k3ssdev/stacompanion/blob/master/app/src/main/java/io/github/k3ssdev/stacompanion/ui/dice/DiceFragment.java"
    click SettFragment "https://github.com/k3ssdev/stacompanion/blob/master/app/src/main/java/io/github/k3ssdev/stacompanion/ui/settings/SettingsFragment.java"
    click CSVM "https://github.com/k3ssdev/stacompanion/blob/master/app/src/main/java/io/github/k3ssdev/stacompanion/ui/characters/CharacterSheetViewModel.java"
    click DVM "https://github.com/k3ssdev/stacompanion/blob/master/app/src/main/java/io/github/k3ssdev/stacompanion/ui/dice/DiceViewModel.java"
    click SVML "https://github.com/k3ssdev/stacompanion/blob/master/app/src/main/java/io/github/k3ssdev/stacompanion/ui/settings/SettingsViewModel.java"
    click CFAdapter "https://github.com/k3ssdev/stacompanion/blob/master/app/src/main/java/io/github/k3ssdev/stacompanion/data/CharacterFragmentAdapter.java"
    click DRAdapter "https://github.com/k3ssdev/stacompanion/blob/master/app/src/main/java/io/github/k3ssdev/stacompanion/ui/dice/DiceResultAdapter.java"
    click SpaceDec "https://github.com/k3ssdev/stacompanion/blob/master/app/src/main/java/io/github/k3ssdev/stacompanion/ui/dice/SpaceItemDecoration.java"
    click CharSheet "https://github.com/k3ssdev/stacompanion/blob/master/app/src/main/java/io/github/k3ssdev/stacompanion/data/CharacterSheet.java"
    click SheetSet "https://github.com/k3ssdev/stacompanion/blob/master/app/src/main/java/io/github/k3ssdev/stacompanion/data/SheetSettings.java"
    click Starship "https://github.com/k3ssdev/stacompanion/blob/master/app/src/main/java/io/github/k3ssdev/stacompanion/data/Starship.java"
    click DbHelper "https://github.com/k3ssdev/stacompanion/blob/master/app/src/main/java/io/github/k3ssdev/stacompanion/data/CharacterDbHelper.java"
    click PdfUtilU "https://github.com/k3ssdev/stacompanion/blob/master/app/src/main/java/io/github/k3ssdev/stacompanion/util/PdfUtil.java"
    click AdsService "https://github.com/k3ssdev/stacompanion/blob/master/app/src/main/java/io/github/k3ssdev/stacompanion/STACompanionAds.java"
    click PDFAsset "https://github.com/k3ssdev/stacompanion/blob/master/app/src/main/assets/STA_personaje.pdf"
    click CIConf "https://github.com/k3ssdev/stacompanion/blob/master/.github/workflows/android_ci.yml"
    click GradleApp "https://github.com/k3ssdev/stacompanion/blob/master/app/build.gradle.kts"
    click GradleRoot "https://github.com/k3ssdev/stacompanion/blob/master/build.gradle.kts"
    click DocRead "https://github.com/k3ssdev/stacompanion/blob/master/README.MD"
    click DocSta "https://github.com/k3ssdev/stacompanion/blob/master/sta_tree.md"

    %% Class Definitions for Styling
    class MActivity,LActivity,SActivity,LglActivity,CSActivity,ChFragment,CSFragment,DTFragment,SkFragment,OtFragment,StFragment,DFragment,SettFragment,CFAdapter,DRAdapter,SpaceDec ui
    class CSVM,DVM,SVML presentation
    class CharSheet,SheetSet,Starship,DbHelper data
    class PdfUtilU,AdsService,PDFAsset utility
    class CIConf,GradleApp,GradleRoot,DocRead,DocSta build
```
