How clementwzk/opencalc works
1. Product shape
- OpenCalc is a single-module Android application packaged in app/, with no server-side component or networked backend in the repository.
- The app is centered on local, offline calculator interaction: user input, expression parsing/evaluation, result formatting, and optional history persistence.
2. Top-level runtime boundary
- The Android app is initialized by OpenCalcApp.kt, then driven through a small set of Activities and one Quick Settings tile service.
- The main runtime surfaces are MainActivity, SettingsActivity, AboutActivity, and MyTileService.
3. Primary UI surface
- MainActivity is the core calculator screen and likely owns the keypad/display interaction, orientation-aware layouts, and history access.
- The repository includes multiple layout qualifiers (land, sw600dp, sw720dp, etc.), showing that the UI adapts across phone/tablet and portrait/landscape form factors.
- The app uses XML layouts and menus rather than a fully Compose-based UI.
4. Expression engine
- The calculator logic is isolated under calculator/.
- Calculator.kt is the execution-facing entry point, while parser/Expression.kt and parser/NumberFormatter.kt indicate a custom algebra/parser layer and formatting layer.
- This is the main non-UI subsystem: it transforms user-entered expressions into evaluated values and formatted display strings.
5. Data flow: input to result
- User actions from the main screen flow into the calculator engine.
- Expressions are parsed and evaluated locally, then results are formatted for display using the number formatter.
- The evaluation result can then be pushed into the history subsystem and reused by the UI.
6. History subsystem
- history/History.kt and history/HistoryAdapter.kt indicate a local history model plus a RecyclerView-style adapter for rendering prior calculations.
- History is a first-class UI feature rather than a separate storage service; it likely backs the expandable history panel or drawer visible from the main activity.
7. Preferences and settings
- MyPreferences.kt, Themes.kt, and util/MyPreferenceMigrator.kt show that user configuration is stored locally and migrated between app versions.
- SettingsActivity exposes user-facing configuration such as theme choice, scientific mode, precision, numbering system, vibration, and other calculator behavior.
- Preferences act as the main cross-cutting state source for UI, formatting, and feature toggles.
8. Theme and presentation layer
- The app has multiple themes: dark, light, AMOLED, and Material You support is called out in the README.
- Themes.kt plus resource files in values-night, styles.xml, colors.xml, and themed drawables drive the visual system.
- TextSizeAdjuster.kt suggests the display adapts font size dynamically to keep long expressions/results readable.
9. Quick Settings / lock-screen integration
- services/MyTileService.kt is an Android SystemUI tile entry point, giving the app a shortcut outside the main activity.
- The README’s “available on locked screen” feature implies the tile or activity flow is designed to work without deep app navigation and possibly from the lock screen context.
10. Dialogs and auxiliary flows
- dialogs/DonationDialog.kt and AboutActivity provide secondary product flows: support, app info, and external links.
- These are UI-only boundaries that do not affect the calculator engine but do affect navigation and user retention.
11. Locale and internationalization
- The repository is heavily localized: there are many values-xx resource directories and a locales_config.xml.
- This means text, numbering/labels, and possibly formatted strings are designed to be language-aware at the resource layer rather than in code.
- The app’s architecture therefore separates stable logic from locale-specific presentation.
12. Resource-driven UI assets
- The app relies on vector drawables and XML menus for all calculator icons and action affordances.
- The resource tree contains dedicated layouts for history items and the main screen, showing that UI composition is primarily declarative and resource-based.
13. Testing boundaries
- Unit tests focus on the pure logic layer: ExpressionUnitTest.kt and NumberFormatterTest.kt.
- Instrumented tests cover Android runtime behavior via MainActivityTests.kt.
- This split reflects the architecture: algorithmic correctness is isolated from Android UI/runtime verification.
14. Build and release pipeline
- The project uses Gradle Kotlin DSL with version catalog support and the standard Android Gradle build.
- fastlane/metadata/android/ and playStore/ indicate a release/marketing pipeline for app store metadata, screenshots, and changelogs, separate from app runtime code.
- This does not affect in-app architecture, but it does show the repo includes distribution assets for multiple stores.
15. Overall system boundary
- The clearest architectural boundary is between the Android presentation layer and the local calculator engine.
- Everything important happens on-device: UI, expression evaluation, formatting, history, settings, and service integration.
- No external API, database server, or sync backend appears to be part of the system.
Main entry points: MainActivity.kt Main screen · OpenCalcApp.kt OpenCalcApp · MyPreferences.kt Preferences · activity_main.xml Layouts
Components 22
Android app
Runtime code, UI, and local state on device.
- OpenCalcApp · Initializes the Android app process and shared app state.
app/src/main/java/com/darkempire78/opencalculator/OpenCalcApp.kt - Main screen · Primary calculator UI, keypad interaction, and display flow.
app/src/main/java/com/darkempire78/opencalculator/activities/MainActivity.kt - Settings · User preferences and behavior configuration surface.
app/src/main/java/com/darkempire78/opencalculator/activities/SettingsActivity.kt - About · App info and secondary navigation flow.
app/src/main/java/com/darkempire78/opencalculator/activities/AboutActivity.kt - Tile service · Quick Settings entry point for launching calculator access.
app/src/main/java/com/darkempire78/opencalculator/services/MyTileService.kt - Preferences · Shared preferences-backed app configuration and migration support.
app/src/main/java/com/darkempire78/opencalculator/MyPreferences.kt - Migrator · Upgrades stored settings across app versions.
app/src/main/java/com/darkempire78/opencalculator/util/MyPreferenceMigrator.kt - Themes · Theme selection and visual mode wiring.
app/src/main/java/com/darkempire78/opencalculator/Themes.kt - Text sizing · Adjusts display text for long expressions and results.
app/src/main/java/com/darkempire78/opencalculator/TextSizeAdjuster.kt - History · Stores prior calculations for reuse in the UI.
app/src/main/java/com/darkempire78/opencalculator/history/History.kt - History list · Renders calculation history entries in the main UI.
app/src/main/java/com/darkempire78/opencalculator/history/HistoryAdapter.kt - Donation dialog · Secondary support and donation flow.
app/src/main/java/com/darkempire78/opencalculator/dialogs/DonationDialog.kt - Scientific mode · Feature toggles and scientific calculator behavior support.
app/src/main/java/com/darkempire78/opencalculator/util/ScientificMode.kt
Calculator engine
Expression parsing, evaluation, and formatting.
- Calculator · Executes calculator actions and bridges UI input to evaluation.
app/src/main/java/com/darkempire78/opencalculator/calculator/Calculator.kt - Expression · Parses and evaluates calculator expressions.
app/src/main/java/com/darkempire78/opencalculator/calculator/parser/Expression.kt - Number format · Formats evaluated values for display and locale behavior.
app/src/main/java/com/darkempire78/opencalculator/calculator/parser/NumberFormatter.kt
Resources
XML layouts, themes, menus, and localized assets.
- Layouts · Declarative screens for calculator, settings, about, dialog, and history items.
app/src/main/res/layout/activity_main.xml - Theme resources · Colors, styles, dimens, and night/theme variants.
app/src/main/res/values/styles.xml - Locales · Localized strings and locale configuration for many languages.
app/src/main/res/xml/locales_config.xml
Release assets
Store metadata and marketing materials.
- Store assets · Fastlane and Play Store marketing/release materials.
fastlane/metadata/android/en-US/full_description.txt
Tests
Logic and Android runtime verification.
- Logic tests · Pure correctness tests for expression evaluation and formatting.
app/src/test/java/com/darkempire78/opencalculator/ExpressionUnitTest.kt - Android tests · Runtime verification of calculator behavior on Android.
app/src/androidTest/java/com/darkempire78/opencalculator/MainActivityTests.kt
Connections 24
- OpenCalcApp → Main screen: starts · App process boots into the main calculator surface.
- OpenCalcApp → Settings: opens · Application exposes settings screen for user configuration.
- OpenCalcApp → About: opens · Application exposes the about/info screen.
- OpenCalcApp → Tile service: registers · App includes a Quick Settings tile entry point.
- Main screen → Calculator: input to eval · User actions are converted into calculator operations.
- Calculator → Expression: parses · Calculator engine delegates expression parsing and evaluation.
- Expression → Number format: formats · Computed values are prepared for display output.
- Main screen → History: records · Completed calculations are added to local history.
- History list → History: renders · History data is bound into a list UI.
- Main screen → History list: shows · Main screen presents prior calculations through the adapter.
- Settings → Preferences: reads/writes · Settings screen persists local user preferences.
- Preferences → Migrator: migrates · Stored settings are upgraded across versions.
- Preferences → Themes: drives · Theme and behavior choices flow from preferences.
- Preferences → Scientific mode: configures · Scientific behavior is controlled by stored preferences.
- Themes → Theme resources: uses · Theme definitions are implemented in resources.
- Main screen → Text sizing: adapts display · Calculator display sizing responds to expression length.
- Layouts → Main screen: defines UI · XML layouts compose the main activity screen.
- Layouts → Settings: defines UI · XML layouts compose the settings screen.
- Layouts → About: defines UI · XML layouts compose the about screen.
- Locales → Layouts: localizes · Strings and locale config supply translated UI text.
- Logic tests → Expression: verifies · Unit tests focus on parser and expression correctness.
- Logic tests → Number format: verifies · Unit tests cover number formatting behavior.
- Android tests → Main screen: verifies · Instrumented tests exercise Android runtime behavior.
- Store assets → OpenCalcApp: packages · Release metadata and marketing assets support distribution.