An offline-first, bilingual (Persian / English) Android scorekeeping and match analytics application for the classic 4-player Persian trick-taking card game Shelem, built with Kotlin, Jetpack Compose, Material Design 3, and Room.
- 3-Step Game Setup & Interactive Table Seating
- Configure team names and all 4 players (
Team 1vs.Team 2). - Visual, interactive card-table layout with counter-clockwise (پادساعتگرد) dealer rotation and one-tap opponent seat swapping.
- Customizable target score (e.g.,
1165,1200), optional 1000+ Point Rule (winHandOnlyOver1000), and optional Ace in Ground (trackAceInGround) tracking.
- Configure team names and all 4 players (
- Two-Phase Round Workflow
- Bid Declaration (
AddRoundBottomSheet): Select the Declarer/Hakem, auto-rotated Dealer, bid amount (100–165), and Naras toggle. - Score Entry (
DeclareScoreBottomSheet): Slider and quick-preset chips for raw points collected (0–165) with real-time score preview, Rule 1000+ restriction indicators, and optional Ace-in-Ground toggle.
- Bid Declaration (
- Rich Match Analytics & Custom Canvas Charts
- Interactive Score Progression Line Chart, Round-by-Round Bar Chart, Outcomes & Win-Share Donut Chart, 5-Axis Team Comparison Radar Chart, and Bid Distribution Histogram drawn directly with Jetpack Compose
Canvas. - Player Performance Leaderboard (MVP Hakem badge, success rate, average bid, max bid made, net Hakem score) and Match Records & Highlights (biggest penalty, most precise/clutch bid, largest cumulative lead, luckiest dealer, Rule 1000+ blocks, and Ace-in-Ground statistics).
- Interactive Score Progression Line Chart, Round-by-Round Bar Chart, Outcomes & Win-Share Donut Chart, 5-Axis Team Comparison Radar Chart, and Bid Distribution Histogram drawn directly with Jetpack Compose
- CSV Export & Sharing (
CsvExporter)- Exports full match metadata and a round-by-round breakdown table to
.csvwith a UTF-8 BOM (\uFEFF) for clean rendering of Persian and English text in Excel and Google Sheets. - Supports saving via Storage Access Framework (
ActivityResultContracts.CreateDocument) or sharing directly throughFileProvider.
- Exports full match metadata and a round-by-round breakdown table to
- Bilingual Localization & Adaptive Theming
- Defaults to Persian (
fa) with RTL layout,Vazirfont (vazir_regular.ttf), and automatic Persian/English numeral formatting (PersianNumberHelper). - Supports runtime Persian/English language switching on Android 13+ (API 33+) via
LocaleManagerandlocales_config.xml. - Custom Felt Green & Gold Material 3 Dark and Light themes, toggled from the Navigation Drawer alongside repository and bug-report email actions.
- Defaults to Persian (
| Category | Technology / Library | Version / Notes |
|---|---|---|
| Language | Kotlin | 2.2.10 |
| Build System | Gradle (Kotlin DSL) + Version Catalog | AGP 9.1.1, KSP 2.3.5 |
| SDK Targets | minSdk = 24, compileSdk = 37, targetSdk = 37 |
Java 11 bytecode |
| UI Framework | Jetpack Compose + Material Design 3 | Compose BOM 2026.09.00 |
| Navigation | Navigation Compose | 2.10.2 (HOME, SETUP, BOARD) |
| Architecture | MVVM + Repository Pattern | AndroidViewModel, StateFlow, collectAsStateWithLifecycle |
| Local Persistence | Room (room-runtime, room-ktx, room-compiler) |
2.8.5 (SQLite, DB version 5) |
| Async / Concurrency | Kotlin Coroutines & Flow | 1.11.0 |
| Graphics & Charts | Jetpack Compose Canvas |
Custom line, bar, donut, and radar charts |
| Testing | JUnit 4, Robolectric, Roborazzi, Compose UI Test | Robolectric 4.17, Roborazzi 1.78.0 |
Dependency versions are centrally managed in gradle/libs.versions.toml.
.
├── build.gradle.kts # Top-level Gradle plugin declarations
├── settings.gradle.kts # Repository config & rootProject.name ("Shelem")
├── metadata.json # AI Studio platform metadata
├── gradle/
│ └── libs.versions.toml # Centralized version catalog
└── app/
├── build.gradle.kts # App module config, signingConfigs, dependencies
├── proguard-rules.pro # ProGuard/R8 rules
└── src/
├── main/
│ ├── AndroidManifest.xml # App entry, RTL & localeConfig, FileProvider
│ ├── java/com/shelem/scoresheet/
│ │ ├── MainActivity.kt # Edge-to-edge host, locale context, ShelemTheme
│ │ ├── data/
│ │ │ ├── AppDatabase.kt # Room database singleton (shelem_database)
│ │ │ ├── GameEntity.kt # Game table, rules & counter-clockwise seating
│ │ │ ├── RoundEntity.kt # Round table (FK cascade to GameEntity)
│ │ │ ├── GameWithRounds.kt # Room @Relation model & team score totals
│ │ │ ├── ShelemDao.kt # Reactive Flow queries & CRUD operations
│ │ │ └── ShelemRepository.kt # Data operations & auto-finish game evaluation
│ │ ├── domain/
│ │ │ ├── RoundResult.kt # Sealed RoundResult, Team enum, CalculatedRoundScores
│ │ │ ├── ScoringEngine.kt # Pure Shelem scoring & Rule 1000+ logic
│ │ │ └── GameStatisticsCalculator.kt # Aggregated KPIs, player stats & records
│ │ ├── ui/
│ │ │ ├── components/
│ │ │ │ ├── GameCard.kt # Home screen match summary card
│ │ │ │ ├── RoundCard.kt # Round card with swipe/delete & status
│ │ │ │ ├── ScoreProgressionLineChart.kt # Interactive cumulative score chart
│ │ │ │ ├── StatisticsCharts.kt # Bar, donut, radar & bid charts
│ │ │ │ └── PlayerAndRecordStatsCards.kt # Player leaderboard & match records
│ │ │ ├── navigation/
│ │ │ │ └── NavGraph.kt # Compose NavHost (home, setup, board/{gameId})
│ │ │ ├── screens/
│ │ │ │ ├── HomeScreen.kt # Match list, ongoing/history, drawer
│ │ │ │ ├── GameSetupScreen.kt # 3-step setup & table seating wizard
│ │ │ │ ├── GameBoardScreen.kt # Live scoreboard, rounds & actions
│ │ │ │ ├── AddRoundBottomSheet.kt # Bid & Hakem/Dealer declaration sheet
│ │ │ │ ├── DeclareScoreBottomSheet.kt # Raw points & live score preview sheet
│ │ │ │ ├── GameStatisticsBottomSheet.kt # Tabbed analytics & charts sheet
│ │ │ │ └── ExportCsvDialog.kt # CSV save & share bottom sheet
│ │ │ ├── theme/
│ │ │ │ ├── Color.kt # Felt green, gold, emerald, red & surface palette
│ │ │ │ ├── Theme.kt # Light/Dark ColorSchemes & RTL/LTR direction
│ │ │ │ └── Type.kt # Material 3 Typography backed by VazirFontFamily
│ │ │ └── viewmodel/
│ │ │ └── ShelemViewModel.kt # UI state flows & ViewModel actions
│ │ └── util/
│ │ ├── CsvExporter.kt # UTF-8 BOM CSV generator & FileProvider share
│ │ ├── LocaleHelper.kt # Default Persian locale & API 33+ switcher
│ │ └── PersianNumberHelper.kt # Persian/English digit conversion & formatting
│ └── res/
│ ├── font/vazir_regular.ttf # Bundled Vazir font
│ ├── values/strings.xml # Default (Persian) strings
│ ├── values-fa/strings.xml # Persian string resources
│ ├── values-en/strings.xml # English string resources
│ ├── xml/locales_config.xml # Per-app language config (fa, en)
│ ├── xml/file_paths.xml # FileProvider cache export path
│ └── mipmap-* / drawable/ # Adaptive launcher icon & vector icons
├── test/
│ ├── java/com/shelem/scoresheet/
│ │ ├── ExampleUnitTest.kt # Scoring, dealer rotation & stats unit tests
│ │ ├── ExampleRobolectricTest.kt # Bilingual terminology & bug-report intent tests
│ │ ├── LocaleBehaviorRobolectricTest.kt # API < 33 vs API 33+ locale behavior tests
│ │ └── GreetingScreenshotTest.kt # Roborazzi Compose screenshot test
│ └── screenshots/greeting.png # Reference Roborazzi screenshot
└── androidTest/
└── java/com/shelem/scoresheet/
└── ExampleInstrumentedTest.kt
The application follows a clean MVVM + Repository architecture with unidirectional data flow:
- Data Layer (
com.shelem.scoresheet.data)AppDatabasemanages the Room SQLite database (shelem_database, schema version5) containinggames(GameEntity) androunds(RoundEntity, linked via foreign key withCASCADEdelete).ShelemDaoexposes reactiveFlowqueries (getOngoingGamesWithRounds,getFinishedGamesWithRounds,getGameById,getRoundsForGame).ShelemRepositorycoordinates scoring calculations before persisting rounds and automatically marks a game finished when the target score or target point lead is reached (and re-opens it if a round is deleted).
- Domain Layer (
com.shelem.scoresheet.domain)ScoringEngineis a stateless object encapsulating all Shelem scoring rules.GameStatisticsCalculatorcomputesComprehensiveGameStatsfrom completed rounds (win streaks, bid brackets, per-player Hakem metrics, 5-axis radar values, match records, and Ace-in-Ground statistics).
- UI Layer (
com.shelem.scoresheet.ui)ShelemViewModelexposesStateFlowstreams (ongoingGamesWithRounds,finishedGamesWithRounds,activeGame,activeRounds,darkThemeEnabled).ShelemNavGraphmanages routing betweenhome,setup, andboard/{gameId}destinations.
Each standard hand contains 165 total card points. Given the Declarer (Hakem) team's bid (bidAmount) and collected raw points (hakemCollectedPoints):
| Outcome | Condition | Declarer Team Score | Opponent Team Score |
|---|---|---|---|
| Shelem (شلم) | hakemCollectedPoints == 165 |
+330 |
0 |
| Made (پُر) | hakemCollectedPoints >= bidAmount (and < 165) |
+hakemCollectedPoints |
165 - hakemCollectedPoints |
| Set (خالی) | 85 <= hakemCollectedPoints < bidAmount |
-bidAmount |
165 - hakemCollectedPoints |
| Double Set (دوبل منفی) | hakemCollectedPoints < 85 |
-2 * bidAmount |
165 - hakemCollectedPoints |
- 1000+ Point Rule (
winHandOnlyOver1000): When enabled (default), if a team's prior cumulative score is>= 1000, it receives0points (instead of positive opponent points) unless it wins that hand (accomplishes its own bid/Shelem or sets the opponent). - Match Win Condition: A match automatically finishes when either team reaches
targetScoreor establishes a lead differenceabs(team1Total - team2Total) >= targetScore. Matches can also be manually finished or resumed from the Game Board. - Dealer Rotation: Counter-clockwise order around the table: Seat
0(Bottom / You) → Seat1(Right Opponent) → Seat2(Top / Teammate) → Seat3(Left Opponent).
- Default Locale: The app initializes in Persian (
fa) across all Android versions viaLocaleHelper.attachBaseContextandensureDefaultPersianLocale. - Runtime Switching: On Android 13+ (API 33+), users can switch between Persian (
fa, RTL) and English (en, LTR) from the Home Navigation Drawer viaLocaleManager. Below API 33, the app locks to Persian and hides the drawer language toggle. - Numerals:
PersianNumberHelperformats scores and numbers using Persian digits (۰–۹) with proper RTL negative sign handling when Persian is active, and standard ASCII digits when English is active.
Note: Run Gradle commands directly with
gradle(or./gradlewin standard local Android Studio environments where the Gradle wrapper is installed).
gradle :app:assembleDebuggradle :app:testDebugUnitTest