Technical Requirement Document (TRD)

1. Technical overview

CoinQuest is a native Android app authored in MIT App Inventor Designer and Blockly. Source consists of eight screen pairs (.scm definitions and .bky logic), project.properties, and bundled assets. The accompanying website is static HTML/CSS/JavaScript; it is not an application backend.

2. System architecture

Android UI event → screen procedure → validation/calculation → TinyDB read/write → refreshed labels, lists, and progress views. Screens share persistent keys through TinyDB. Help and Screen1 do not declare TinyDB; financial screens do. No FirebaseDB, CloudDB, Web, account, PHP, or MySQL component was found in the screen definitions inspected.

3. Development platform

MIT App Inventor Designer defines Forms, arrangements, labels, buttons, lists, inputs, images, pickers, and nonvisible components. Blockly provides event handlers, procedures, local/global variables, list operations, formatting, and calculations. The specific App Inventor server/compiler revision used for production requires confirmation.

4. Software requirements

Maintenance requires a browser supported by MIT App Inventor, the AIA source, and access to the project/build environment. Companion or an emulator may be used for development, with a signed Android build for release validation. The website needs a modern browser supporting dialog; direct documentation links remain available without modal support. No website framework, database server, or package installation is required.

5. Hardware requirements

An Android device compatible with the Play release is required for installation. The source minimum SDK is 24 (Android 7.0). A development computer capable of running the selected browser and optional emulator is needed. Minimum RAM, storage, and processor targets have not been measured and require confirmation; do not present arbitrary device specifications as verified.

6. Application components

Verified component types: Form, VerticalArrangement, VerticalScrollArrangement, HorizontalArrangement, Label, Button, Image, TextBox, DatePicker, Spinner, ListView, TinyDB, Notifier, Clock, and Sound. Clocks control loading, transient feedback, mascot effects, celebration effects, and current-date support for report filters. Sound components provide optional click, income/expense, coin, error, reward, level-up, and completion feedback.

7. Screen architecture

8. Data storage architecture

TinyDB stores local tagged values shared between screens. Income and expense records are lists of display strings using the separator - ; parsers split these values to recover amount, category, and date. Totals are stored separately. Completion history is a list accessed through helper procedures. This representation is not a relational database and has no verified server-side mirror.

9. TinyDB usage

Blocks provide zero, empty-list, or other appropriate defaults when reading absent values. Validate existing-data behavior and any future migration on real upgrade installations. TinyDB use does not imply encryption.

10. Data flow

1. Initialize financial screen and retrieve TinyDB values/defaults.
2. Validate entered fields when Save/Add is tapped.
3. Format and append a transaction or update a goal; persist associated values.
4. Refresh screen labels and lists; Dashboard reads shared totals.
5. History combines lists and applies type/category predicates.
6. Reports parses records, accumulates category/month lists, and applies selected period filters.
7. Savings logic checks unclaimed thresholds, updates XP/badges, and records completion before/reset around the celebration workflow.

11. Functional implementation

Key procedures include refreshIncome, refreshExpenses, refreshDashboard, refreshQuest, refreshHistory, refreshReports, mfRefresh, refreshSavings, claimMilestones, recordCompletedGoal, refreshCompletedGoals, and showStep. Dashboard and History use cached/signature values to avoid some redundant refresh work. gNavBusy guards navigation. Source includes financial tips and milestone-based quests; it does not establish an independent recurring-challenges subsystem.

12. Algorithms and calculations

• Current balance = startingBalance + totalIncome − totalExpenses.
• Monthly net = selected-month income − selected-month expenses; starting balance is not monthly earnings.
• Savings percentage derives from savingsProgress / savingsGoal × 100, with a zero-target guard and rounding for display; remaining amount and progress bars use goal/progress values.
• Milestones are 25%, 50%, 75%, and 100%, awarding 25, 50, 75, and 150 XP respectively, subject to claimed-state and goal eligibility checks. The target must be at least ₱100 to earn XP.
• The source Help specifies level thresholds: level 1 at 0 XP; level 2 at 100; level 3 at 300; level 4 at 600; level 5 at 1,000. Blockly contains levelFromXP, xpFloor, and xpNext procedures.
• Entering existing current savings when saving a goal marks reached milestones without awarding XP. Completion-signature bookkeeping avoids duplicate completion entries.
• Amounts are formatted as pesos with two decimal places and separate negative handling. Category/month reports sum parsed transaction amounts.

Confirm boundary cases and reward-reset behavior by execution; Help text is corroborating source evidence, not a replacement for runtime testing.

13. Input validation

Income requires source, numeric amount above zero, and a selected date. Expenses require name, positive numeric amount, category, and date. Goal creation requires name and positive target; current savings must be numeric and nonnegative. Savings contributions must be positive with an active goal. Starting balance permits zero and positive numbers. TextBox numeric configuration is supplemented by NUMBER and comparison blocks. Whitespace-only text, delimiter-containing names, very large numbers, and decimal edge cases require testing.

14. Error handling

Screen procedures show field-specific inline feedback and optional error sounds; Clock components clear transient messages. Empty lists show explanatory labels/images. Reports include parsing helpers and fallback category labels. No verified global crash reporting or transaction rollback system exists. Review malformed stored records and interrupted multi-tag writes before claiming recovery guarantees.

15. Security and privacy

No cloud/authentication component is declared in the inspected screens. The source property useslocation=false is not proof that the compiled manifest has no permissions. Do not claim encrypted storage, disabled Android backup, or absence of all network traffic without examining the exact release binary and runtime behavior. Reconcile the draft policy with Play Data Safety and actual retention/deletion controls. The website support form prepares a mailto message and does not submit to a backend.

16. Performance requirements

Source uses cached dashboard/history state, bounded presentation heights, and event-driven refreshes. Record parsing and aggregation involve list scans; larger histories need profiling. Proposed target: common save/filter/navigation actions within one second for 1,000 records on an agreed reference device, without sustained animation lag. Test results and device characteristics must be recorded before treating this as achieved.

17. Android compatibility

Project properties specify androidminsdk=24, sizing=Responsive, defaultfilescope=App, and useslocation=false. Exact target SDK, merged permissions, signing certificate, device exclusions, and production binary metadata require verification from the AAB/Play Console. Exercise Android back navigation, lifecycle interruption, keyboard visibility, small displays, large text, and sound settings across supported devices.

18. Testing requirements

Execute the PRD acceptance matrix on the production build. Include invalid inputs; persistence and upgrade tests; empty/large histories; month/year boundaries; category filters; balance reconciliation; zero/negative and decimal values; repeated milestone visits; goal changes; duplicate completion prevention; sound preference; Help return navigation; and offline use. Inspect the exact AAB permissions and network behavior separately. Website checks must cover all pages, assets, Play URLs, Help keyboard/focus behavior, responsive layout, and print output. See the dated validation record for checks actually performed.

19. Build and deployment process

1. Import the reviewed AIA into MIT App Inventor and retain a versioned source backup.
2. Confirm package identity appinventor.ai_leijigaviola.CoinQuest and approved release metadata.
3. Build the Android App Bundle using the established project signing key; preserve the key securely.
4. Inspect/test the signed artifact, including upgrade behavior, compatibility, permissions, and Data Safety consistency.
5. Upload to the appropriate Play Console release and complete its review/release process. Production availability is developer-confirmed; this task does not upload a new app build.
6. Update js/config.js for website release metadata; deploy HTML, css, js, assets, and docs to static HTTPS hosting. No application backend is required.

Signing setup, exact build compiler, published AAB hash, and production website domain remain to be supplied. Root AIA/AAB files are development artifacts, not primary download links.

20. Maintenance and future enhancements

Maintain release values centrally in js/config.js. Reinspect source and update the evidence and requirements when behavior changes. Before changing record structure, design a versioned TinyDB migration and test upgrades. Proposed enhancements include structured records, edit/delete, export/recovery, accessibility work, and automated app tests. Any future remote services require new privacy disclosures and security requirements. Instructor template, formal manual, project schedule/team details, and evaluation results remain inputs to the next phase.