NumPairs is a native Android arithmetic deduction puzzle.
Players complete hidden expressions on a board by using numbers from a strip. The project is built iteratively through documented product milestones.
- 📦 PRD v12 App Versioning & Google Play Delivery defines the app-release identity and staged Google Play delivery contract independently from product and persisted-data versions.
NumPairs now provides five persistent color-only themes: Warm, Frost, Obsidian, Terminal, and Ember. Typography, shapes, spacing, elevation, layout, controls, and gameplay meanings remain shared across them.
v11 groups normal generated play into Quick and Classic while preserving the stable internal
3 Pairs, 4 Pairs, and 8 Pairs challenge identities. Quick exposes Low and Medium and selects
the matching 3 Pairs challenge 35% of the time and 4 Pairs challenge 65% of the time. Classic
exposes the original full-board 8 Pairs Medium and 8 Pairs Hard challenges. Generated feedback
continues using subtle accepted-assignment haptics, newly-correct tile motion, a brief completion
celebration, and a successor-ready replay transition.
Daily Challenge selects one deterministic 4 Pairs Low puzzle for each device-local calendar
date. Its exact progress and local completion history use a separate versioned aggregate, so one
normal generated session and one Daily Session may remain resumable at the same time. The
state-aware Menu action, monthly completion calendar, and non-spoiling textual share result work
without accounts or a server.
- The documentation-first product and architecture contract is implemented.
- Quick and Classic are delivered through dependency-ordered atomic issues and Pull Requests.
- Daily Challenge retains its deterministic v10 recipe and independent persistence boundary.
Historical milestone snapshots:
- 🔧 PRD v0 Playable Prototype
- ✨ PRD v1 Product Polish & Technical Hardening
- 🧩 PRD v2 Puzzle Generation & Replay Loop
- 🎓 PRD v3 Guided Play & Rules Onboarding
- 🎨 PRD v4 Visual Design System & UI Refinement
- 🧠 PRD v5 Bigger Challenges with 8 Pairs
- 🎓 PRD v6 Guided First Run
- 🔁 PRD v7 Reliable Sessions & Replay Controls
- 📈 PRD v8 Difficulty Selection & Challenge Expansion
- ✨ PRD v9 Game Feel & Personalization
- 🗓️ PRD v10 Quick Play & Daily Challenge
PRDs preserve the product requirements and planning context for each milestone. Current generated-mode and profile behavior is also documented in puzzle-generation.md.
The generated catalog contains six implemented profiles, including the v11
3 Pairs Medium profile. Normal generated play stores one exact
resumable session shared by every generated challenge, restores committed progress after process
death, and keeps the current puzzle visible until a validated successor is stored and ready.
Daily progress and completion history remain independently persisted in their own aggregate.
- Kotlin
- Jetpack Compose
- Gradle Kotlin DSL
- Android Studio
The puzzle core uses a small domain layer guided by the project's ubiquitous language and DDD-inspired modeling.
Current core concepts:
PuzzleBoardTileExpressionOperatorStrip
app/
├── src/main/java/org/cescfe/numpairs/
│ ├── domain/
│ ├── feature/
│ ├── data/
│ └── ui/
docs/
├── product/
├── technical/
│ ├── adr/
│ ├── code-quality.md
│ └── delivery-workflow.md
├── game-rules.md
└── ubiquitous-language.md
Core responsibilities:
domain: puzzle model, rules, validation, assignments, and generated puzzle logic.feature: Menu, Tutorial, Quick, Classic, Daily Challenge, generated modes, and reusable Game behavior.data: seed puzzle, persistence-backed preferences, generated-session snapshot, and Daily aggregate.ui: app navigation, theme, and shared visual defaults.
- Product Requirements Documents:
docs/product/prd/ - Visual design system: visual-design-system.md
- Rules helper requirements: rules-helper.md
- Puzzle generation: puzzle-generation.md
- Current UI behavior: ui-behavior.md
- Generated-session persistence: generated-session-persistence.md
- Daily Challenge persistence: daily-challenge-persistence.md
- Platform branding decision: ADR-004
- Daily cadence decision: ADR-006
- Generated play-option decision: ADR-007
- Local upload signing: release-signing.md
- UX decisions:
docs/product/ux-decisions.md - Architectural Decision Records:
docs/technical/adr/ - Delivery workflow: delivery-workflow.md
- Code quality guidelines: code-quality.md
- Game rules:
docs/game-rules.md - Ubiquitous Language:
docs/ubiquitous-language.md
- Open the project in Android Studio
- Sync Gradle
- Run on emulator or Android device
# Run unit tests
./gradlew testDebugUnitTest
# Run instrumented UI tests on a connected emulator/device
./gradlew connectedDebugAndroidTest# Check all formatting
./gradlew spotlessCheck
# Apply formatting
./gradlew spotlessApply
# Run all quality checks
./gradlew checkMIT License