Fellowship Housing Budget Tracker — Tester Documentation

1. What this app is

The Fellowship Housing Budget Tracker is a simple, mobile-first web application that helps families track their monthly income and expenses. It is built as a Proof of Concept (POC) — a working prototype intended to validate the core user experience, gather feedback, and de-risk technical decisions before we invest in a full native mobile app.

POC scope: This is not a finished product. Some screens are stubs ("Coming soon"), some flows have rough edges, and some data is not yet persisted across all surfaces. Your feedback as testers is the primary point of building it.

2. What we're trying to do

The POC has three goals:

Validate the user experience. Can our target users (see below) actually use this to set a budget and track expenses without help?
Prove the architecture. The backend is an API-first PHP service so the same endpoints can later power a native mobile app without a rewrite.
Validate integrations. Confirm that SMS verification (Sinch), file storage (Cloudinary), and database hosting work end-to-end on our staging stack.

3. Who it's for

The end users are single mothers in Fellowship Housing's program, many of whom have low financial literacy and may be using a budgeting tool for the first time. This shapes every design decision:

Plain language — no financial jargon.
Phone-number login (no passwords to remember).
Bilingual support (English / Spanish).
Mobile-first layout — many users will only have a phone.
Encouraging tone — the app should feel supportive, not punitive.

When testing, please mentally place yourself in this audience. If something would confuse a first-time user, that's a bug worth reporting even if it works "correctly."

4. How it generally works

The user journey

Sign in with a phone number or email. The system sends a 6-digit verification code.

Enter the code to log in. The session lasts 30 days.

Set up a budget by adding income sources and expense categories with monthly amounts.

Log expenses as they happen. Each transaction is tagged to a budget category.

See the running totals — remaining balance, category spend vs. budget.

The technical shape

The app is a single-page web app (HTML / CSS / vanilla JavaScript) talking to a PHP REST API backed by MySQL. There is no framework on the frontend — this keeps the POC small and portable.

Layer	Technology	Notes
Frontend	Vanilla JS, HTML5, CSS3	Single-page, mobile-first.
Backend API	PHP 7.4+ with PDO	RESTful JSON, token auth.
Database	MySQL 5.7+	Hosted on staging.
SMS	Sinch API	For verification codes.
File storage	Cloudinary	For receipts (planned).
Web server	Apache + mod_rewrite	SPA routing via .htaccess.

5. Accessing the app

Open the staging URL provided by the dev team in a modern browser (Chrome, Safari, Edge, or Firefox). The app works on:

Mobile — the primary experience. Test in portrait orientation.
Tablet — should look reasonable.
Desktop — works for testing convenience, but layout is mobile-first.

Tip: If something looks broken after a deploy, do a hard refresh (Ctrl + Shift + R on Windows, Cmd + Shift + R on Mac) to clear the cached CSS/JS.

6. Logging in (auth flow)

There is no password. Auth is done via a one-time code:

Enter a phone number (any format works: 5551234567, (555) 123-4567, +1-555-123-4567) or an email address.
Click Send Code.
You'll receive a 6-digit code by SMS or email.
Enter the code on the next screen and click Login.

If you don't receive the code: SMS delivery depends on Sinch being configured for the test environment. If you're testing in dev mode, the code may be written to the PHP error log instead of being sent. Ask the dev team for the most recent code, or have them query the verification_codes table.

Codes expire after 10 minutes.
Each phone/email is rate-limited to 3 codes per hour.
Once logged in, your session lasts 30 days.

7. Features to test

Budget tab

The home screen after login. Shows a summary card at the top (income, expenses, remaining) and two sections below for income and expense budgets.

Tap + Add Income to add a monthly income source (e.g. Salary $2,000).
Tap + Add Expense to set a monthly budget for a category (e.g. Rent $800).
Totals at the top should update immediately.
The "remaining" amount should be green when positive and red when over budget.

Expenses tab

Where you log actual transactions as they happen.

Tap + Add Expense, enter a description ("Grocery run"), pick a category, enter an amount.
The transaction shows up in the list.
Switch back to the Budget tab — the matching category should show the spent amount, and the remaining should reflect it.

Goals / Reports / Support tabs

These tabs exist in the navigation but currently show "Coming soon" placeholders. That is expected for the POC. You can still tap them to confirm navigation works.

Language switching

The login screen has a language selector (English / Español). Switching should change UI strings on supported screens. Spanish coverage is partial — please flag any English text that should be translated.

Logout

Tap the logout icon in the top-right of the header. You should be returned to the login screen and your session cleared.

8. Feature status at a glance

Feature	Status	Notes
Phone & email auth	Working	SMS via Sinch, code valid 10 min.
Add income & expense budgets	Working	30+ default categories.
Log expense transactions	Working	Linked to budget categories.
Budget summary totals	Working	Income, expenses, remaining.
Bottom-nav navigation	Working	5 tabs.
Logout	Working
Spanish translation	Partial	Some screens not yet translated.
Goals tab	Not started	Placeholder only.
Reports / charts	Not started	Placeholder only.
Support / community	Not started	Placeholder only.
Receipt upload	Not started	Cloudinary wired but no UI.
Split transactions	Not started	Planned.
Push notifications	Not started	Planned.

9. Suggested test plan

If you have ~20 minutes, walk through this happy path end-to-end:

Open the app on your phone. Confirm only the login screen is visible.
Enter your phone number and request a code.
Enter the code and log in.
Add an income: Salary — $2,000.
Add three expense budgets: Rent $800, Groceries $400, Transportation $200.
Confirm the summary card shows: income $2,000, expenses $1,400, remaining $600.
Switch to Expenses.
Log a transaction: "Walmart" — Groceries — $85.
Log another: "Gas station" — Transportation — $45.
Switch back to Budget. Confirm Groceries now shows $85 spent and Transportation $45 spent.
Tap each of the other tabs — confirm they show "Coming soon" without errors.
Log out. Confirm you're back at the login screen.
Log back in. Confirm your data is still there.

Then explore freely — try edge cases:

Add an expense larger than your income. Does the "remaining" go red?
Try a phone number with weird formatting.
Try requesting a code, waiting 11 minutes, then using it.
Switch language mid-session.
Rotate your phone — does the layout hold up?
Try the same flow on a different browser.

10. Tester checklist

Print or copy this. Tick off as you go and note anything that didn't behave as expected.

Login screen appears on first load (no other screens visible).
Can request a verification code by phone number.
Can request a verification code by email.
Code arrives within a reasonable time (or logged in dev mode).
Login succeeds with the correct code.
Login fails gracefully with the wrong code.
App screen appears after successful login.
Budget summary shows $0.00 for a brand-new user.
Can add an income item.
Can add an expense budget item.
Totals update immediately after adding items.
Remaining amount turns red when expenses exceed income.
Bottom nav switches between Budget, Expenses, Goals, Reports, Support.
Can log a transaction in the Expenses tab.
Transaction list shows the new transaction.
Spent amount on Budget tab updates after logging a transaction.
Logout returns to login screen.
Re-login restores previously entered data.
Language switcher visibly changes UI text.
Layout works on mobile portrait.
Layout works on mobile landscape.
No JavaScript errors in the browser console (F12 to check).

11. Known limitations

Spanish is incomplete. Login and core budget screens are translated; deeper screens may still be in English.
No offline support. The app needs an internet connection.
No "edit" or "delete" UI for budget items or transactions in some places. If you need to fix a mistake, the dev team may need to clean it up in the database for now.
Goals, Reports, and Support tabs are placeholders. They intentionally show "Coming soon."
No password reset flow — because there is no password. If you can't get a code, contact the dev team.
SMS in dev mode may write codes to a server log instead of sending real SMS. The dev team can retrieve them.
Browser caching can occasionally serve stale CSS/JS after a deploy. Hard refresh fixes this.

12. Reporting issues

When you find a bug, please include:

What you did — the exact steps to reproduce.
What you expected to happen.
What actually happened.
Device & browser — e.g. "iPhone 14, Safari" or "Pixel 7, Chrome 120".
A screenshot or short screen recording if you can.
The phone number / email you used to log in (helps the dev team find your data).
Approximate time the issue happened (helps with log lookup).

Anything that confused you counts as a bug. Even if the app technically did what it was supposed to, if a real user (a single mother using this for the first time on her phone) would have been confused, that's worth reporting.

Send reports to the development team at Project World Impact via your usual channel (Slack, email, or your assigned ticket tracker).