How k3ssdev/stacompanion works
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).